File 2531-compiler-Update-compile-module-to-use-spec... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 2531-compiler-Update-compile-module-to-use-specs.patch of Package erlang (Revision 54461a2357af3de1f765489d2fd0ee14)

Currently displaying revision 54461a2357af3de1f765489d2fd0ee14 , Show latest

From 85c4e2fad973a1500a53913e26ff12d6007297fc Mon Sep 17 00:00:00 2001
From: Lukas Larsson <lukas@erlang.org>
Date: Mon, 9 Oct 2023 15:32:24 +0200
Subject: [PATCH 1/3] compiler: Update compile module to use specs

---
 lib/compiler/doc/specs/.gitignore |  0
 lib/compiler/doc/src/Makefile     |  2 +
 lib/compiler/doc/src/compile.xml  | 89 ++++++++++++++++---------------
 lib/compiler/doc/src/specs.xml    |  4 ++
 lib/compiler/src/compile.erl      | 18 ++++---
 5 files changed, 61 insertions(+), 52 deletions(-)
 create mode 100644 lib/compiler/doc/specs/.gitignore
 create mode 100644 lib/compiler/doc/src/specs.xml

diff --git a/lib/compiler/doc/src/Makefile b/lib/compiler/doc/src/Makefile
index 57c7bc2dc7..ae60abba08 100644
--- a/lib/compiler/doc/src/Makefile
+++ b/lib/compiler/doc/src/Makefile
@@ -46,6 +46,8 @@ XML_FILES = \
 	$(BOOK_FILES) $(XML_NOTES_FILES) \
 	$(XML_PART_FILES) $(XML_REF3_FILES) $(XML_APPLICATION_FILES)
 
+TOP_SPECS_FILE = specs.xml
+
 $(XMLDIR)/%.xml: ../../internal_doc/%.md $(ERL_TOP)/make/emd2exml
 	$(ERL_TOP)/make/emd2exml $< $@
 
diff --git a/lib/compiler/doc/src/compile.xml b/lib/compiler/doc/src/compile.xml
index d7bfc63c83..a623281eb7 100644
--- a/lib/compiler/doc/src/compile.xml
+++ b/lib/compiler/doc/src/compile.xml
@@ -39,19 +39,46 @@
 </description>
 
 <datatypes>
- <datatype>
- <name>option() = term()</name>
- <desc>See <seemfa marker="#file/2">file/2</seemfa> for detailed description</desc>
- </datatype>
- <datatype>
- <name>forms() = term()</name>
- <desc>List of Erlang abstract or Core Erlang format representations, as used by <seemfa marker="#forms/2">forms/2</seemfa></desc>
- </datatype>
+ <datatype>
+ <name name="abstract_code"/>
+ </datatype>
+ <datatype>
+ <name name="bin_ret"/>
+ </datatype>
+ <datatype>
+ <name name="comp_ret"/>
+ </datatype>
+ <datatype>
+ <name name="err_ret"/>
+ </datatype>
+ <datatype>
+ <name name="error_description"/>
+ </datatype>
+ <datatype>
+ <name name="error_info"/>
+ </datatype>
+ <datatype>
+ <name name="errors"/>
+ </datatype>
+ <datatype>
+ <name name="forms"/>
+ <desc>List of Erlang abstract or Core Erlang format representations, as used by <seemfa marker="#forms/2">forms/2</seemfa>.</desc>
+ </datatype>
+ <datatype>
+ <name name="mod_ret"/>
+ </datatype>
+ <datatype>
+ <name name="option"/>
+ <desc>See <seemfa marker="#file/2">file/2</seemfa> for detailed description.</desc>
+ </datatype>
+ <datatype>
+ <name name="warnings"/>
+ </datatype>
 </datatypes>
 
 <funcs>
 <func>
- <name since="OTP 19.0">env_compiler_options()</name>
+ <name name="env_compiler_options" arity="0" since="OTP 19.0"/>
 <fsummary>
 	Compiler options defined via the environment variable
 	<c>ERL_COMPILER_OPTIONS</c>
@@ -64,7 +91,7 @@
 </desc>
 </func>
 <func>
- <name since="">file(File)</name>
+ <name name="file" arity="1" since=""/>
 <fsummary>Compiles a file.</fsummary>
 <desc>
 Is the same as
@@ -74,14 +101,8 @@
 </func>
 
 <func>
- <name since="">file(File, Options) -> CompRet</name>
+ <name name="file" arity="2" since=""/>
 <fsummary>Compiles a file.</fsummary>
- <type>
- <v>CompRet = ModRet | BinRet | ErrRet</v>
- <v>ModRet = {ok,ModuleName} | {ok,ModuleName,Warnings}</v>
- <v>BinRet = {ok,ModuleName,Binary} | {ok,ModuleName,Binary,Warnings}</v>
- <v>ErrRet = error | {error,Errors,Warnings}</v>
- </type>
 <desc>
 Compiles the code in the file <c>File</c>, which is an
 	 Erlang source code file without the <c>.erl</c> extension.
@@ -935,7 +956,7 @@ module.beam: module.erl \
 </func>
 
 <func>
- <name since="">forms(Forms)</name>
+ <name name="forms" arity="1" since=""/>
 <fsummary>Compiles a list of forms.</fsummary>
 <desc>
 Is the same as
@@ -945,19 +966,8 @@ module.beam: module.erl \
 </func>
 
 <func>
- <name since="">forms(Forms, Options) -> CompRet</name>
+ <name name="forms" arity="2" since=""/>
 <fsummary>Compiles a list of forms.</fsummary>
- <type>
- <v>Forms = <seetype marker="#forms">forms()</seetype></v>
- <v>forms() = [<seetype marker="stdlib:erl_parse#abstract_form">erl_parse:abstract_form</seetype>] | <seeerl marker="cerl#type-c_module">cerl:c_module()</seeerl></v>
- <v>Options = [<seetype marker="#option">option()</seetype>]</v>
- <v>CompRet = BinRet | ErrRet</v>
- <v>BinRet = {ok,ModuleName,BinaryOrCode} | {ok,ModuleName,BinaryOrCode,Warnings}</v>
- <v>ModuleName = module()</v>
- <v>BinaryOrCode = binary() | term()</v>
- <v>ErrRet = error | {error,Errors,Warnings}</v>
- <v>Warnings = Errors = [{<seetype marker="kernel:file#filename">file:filename()</seetype>, [{<seetype marker="stdlib:erl_anno#location">erl_anno:location()</seetype> | 'none', module(), term()}]}]</v>
- </type>
 <desc>
 Analogous to <c>file/1</c>, but takes a list of forms (in
 	 either Erlang abstract or Core Erlang format representation)
@@ -971,11 +981,8 @@ module.beam: module.erl \
 </func>
 
 <func>
- <name since="">format_error(ErrorDescriptor) -> chars()</name>
+ <name name="format_error" arity="1" since=""/>
 <fsummary>Formats an error descriptor.</fsummary>
- <type>
- <v>ErrorDescriptor = errordesc()</v>
- </type>
 <desc>
 Uses an <c>ErrorDescriptor</c> and returns a deep list of
 	 characters that describes the error. This function is
@@ -986,11 +993,8 @@ module.beam: module.erl \
 </func>
 
 <func>
- <name since="">output_generated(Options) -> true | false</name>
+ <name name="output_generated" arity="1" since=""/>
 <fsummary>Determines whether the compiler generates an output file.</fsummary>
- <type>
- <v>Options = [term()]</v>
- </type>
 <desc>
 Determines whether the compiler generates a <c>beam</c>
 	file with the given options. <c>true</c> means that a <c>beam</c>
@@ -1001,7 +1005,7 @@ module.beam: module.erl \
 </func>
 
 <func>
- <name since="">noenv_file(File, Options) -> CompRet</name>
+ <name name="noenv_file" arity="2" since="" />
 <fsummary>Compiles a file (ignoring <c>ERL_COMPILER_OPTIONS)</c>.</fsummary>
 <desc>
 Works like <seemfa marker="#file/2">file/2</seemfa>,
@@ -1011,7 +1015,7 @@ module.beam: module.erl \
 </func>
 
 <func>
- <name since="">noenv_forms(Forms, Options) -> CompRet</name>
+ <name name="noenv_forms" arity="2" since="" />
 <fsummary>Compiles a list of forms (ignoring <c>ERL_COMPILER_OPTIONS)</c>.</fsummary>
 <desc>
 Works like <seemfa marker="#forms/2">forms/2</seemfa>,
@@ -1021,12 +1025,9 @@ module.beam: module.erl \
 </func>
 
 <func>
- <name since="">noenv_output_generated(Options) -> true | false</name>
+ <name name="noenv_output_generated" arity="1" since="" />
 <fsummary>Determines whether the compiler generates an output file 
 (ignoring <c>ERL_COMPILER_OPTIONS)</c>.</fsummary>
- <type>
- <v>Options = [term()]</v>
- </type>
 <desc>
 Works like
 	<seemfa marker="#output_generated/1">output_generated/1</seemfa>,
diff --git a/lib/compiler/doc/src/specs.xml b/lib/compiler/doc/src/specs.xml
new file mode 100644
index 0000000000..01df8b6d6e
--- /dev/null
+++ b/lib/compiler/doc/src/specs.xml
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<specs xmlns:xi="http://www.w3.org/2001/XInclude">
+ <xi:include href="../specs/specs_compile.xml"/>
+</specs>
diff --git a/lib/compiler/src/compile.erl b/lib/compiler/src/compile.erl
index 3abcb1df6e..49856b448f 100644
--- a/lib/compiler/src/compile.erl
+++ b/lib/compiler/src/compile.erl
@@ -82,22 +82,24 @@
 
 -define(DEFAULT_OPTIONS, [verbose,report_errors,report_warnings]).
 
--spec file(module() | file:filename()) -> comp_ret().
+-spec file(module() | file:filename()) ->
+ CompRet :: comp_ret().
 
 file(File) -> file(File, ?DEFAULT_OPTIONS).
 
--spec file(module() | file:filename(), [option()] | option()) -> comp_ret().
+-spec file(module() | file:filename(), Options :: [option()] | option()) ->
+ CompRet :: comp_ret().
 
 file(File, Opts) when is_list(Opts) ->
 do_compile({file,File}, Opts++env_default_opts());
 file(File, Opt) ->
 file(File, [Opt|?DEFAULT_OPTIONS]).
 
--spec forms(abstract_code()) -> comp_ret().
+-spec forms(forms()) -> CompRet :: comp_ret().
 
 forms(Forms) -> forms(Forms, ?DEFAULT_OPTIONS).
 
--spec forms(forms(), [option()] | option()) -> comp_ret().
+-spec forms(forms(), Options :: [option()] | option()) -> CompRet :: comp_ret().
 
 forms(Forms, Opts) when is_list(Opts) ->
 do_compile({forms,Forms}, [binary|Opts++env_default_opts()]);
@@ -108,7 +110,7 @@ forms(Forms, Opt) when is_atom(Opt) ->
 %% would have generated a Beam file, false otherwise (if only a binary or a
 %% listing file would have been generated).
 
--spec output_generated([option()]) -> boolean().
+-spec output_generated(Options :: [option()]) -> boolean().
 
 output_generated(Opts) ->
 noenv_output_generated(Opts++env_default_opts()).
@@ -118,7 +120,7 @@ output_generated(Opts) ->
 %% for default options.
 %%
 
--spec noenv_file(module() | file:filename(), [option()] | option()) -> comp_ret().
+-spec noenv_file(module() | file:filename(), Options :: [option()] | option()) -> comp_ret().
 
 noenv_file(File, Opts) when is_list(Opts) ->
 do_compile({file,File}, Opts);
@@ -132,7 +134,7 @@ noenv_forms(Forms, Opts) when is_list(Opts) ->
 noenv_forms(Forms, Opt) when is_atom(Opt) ->
 noenv_forms(Forms, [Opt|?DEFAULT_OPTIONS]).
 
--spec noenv_output_generated([option()]) -> boolean().
+-spec noenv_output_generated(Options :: [option()]) -> boolean().
 
 noenv_output_generated(Opts) ->
 {_,Passes} = passes(file, expand_opts(Opts)),
@@ -282,7 +284,7 @@ expand_opt({check_ssa,Tag}, Os) ->
 [check_ssa, Tag | Os];
 expand_opt(O, Os) -> [O|Os].
 
--spec format_error(error_description()) -> iolist().
+-spec format_error(ErrorDescription :: error_description()) -> string().
 
 format_error({obsolete_option,Ver}) ->
 io_lib:fwrite("the ~p option is no longer supported", [Ver]);
-- 
2.35.3

Places

File 2531-compiler-Update-compile-module-to-use-specs.patch of Package erlang (Revision 54461a2357af3de1f765489d2fd0ee14)

Places