File 1951-compiler-Update-compile-module-to-use-specs.patch of Package erlang
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><p>See <seemfa marker="#file/2">file/2</seemfa> for detailed description</p></desc>
- </datatype>
- <datatype>
- <name>forms() = term()</name>
- <desc><p>List of Erlang abstract or Core Erlang format representations, as used by <seemfa marker="#forms/2">forms/2</seemfa></p></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><p>List of Erlang abstract or Core Erlang format representations, as used by <seemfa marker="#forms/2">forms/2</seemfa>.</p></desc>
+ </datatype>
+ <datatype>
+ <name name="mod_ret"/>
+ </datatype>
+ <datatype>
+ <name name="option"/>
+ <desc><p>See <seemfa marker="#file/2">file/2</seemfa> for detailed description.</p></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>
<p>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>
<p>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>
<p>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>
<p>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>
<p>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>
<p>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>
<p>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>
<p>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>
<p>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
