File 0189-parsetools-Use-types-and-specs-for-documen... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 0189-parsetools-Use-types-and-specs-for-documentation.patch of Package erlang (Revision 1e94e72e3f4fed1ca9cd5c2fd777ed02)

Currently displaying revision 1e94e72e3f4fed1ca9cd5c2fd777ed02 , Show latest

From f673f30f37627eefc5367cba1baa0a037c43dfb6 Mon Sep 17 00:00:00 2001
From: Hans Bolinder <hasse@erlang.org>
Date: Mon, 2 Nov 2020 11:52:22 +0100
Subject: [PATCH 1/2] parsetools: Use types and specs for documentation

---
 lib/parsetools/doc/specs/.gitignore |   1 +
 lib/parsetools/doc/src/Makefile     |   2 +
 lib/parsetools/doc/src/leex.xml     | 102 +++++++++++-----------
 lib/parsetools/doc/src/specs.xml    |   5 ++
 lib/parsetools/doc/src/yecc.xml     | 126 ++++++++++++++--------------
 lib/parsetools/src/leex.erl         |  36 +++++++-
 lib/parsetools/src/yecc.erl         |  37 +++++++-
 7 files changed, 190 insertions(+), 119 deletions(-)
 create mode 100644 lib/parsetools/doc/specs/.gitignore
 create mode 100644 lib/parsetools/doc/src/specs.xml

diff --git a/lib/parsetools/doc/specs/.gitignore b/lib/parsetools/doc/specs/.gitignore
new file mode 100644
index 0000000000..322eebcb06
--- /dev/null
+++ b/lib/parsetools/doc/specs/.gitignore
@@ -0,0 +1 @@
+specs_*.xml
diff --git a/lib/parsetools/doc/src/Makefile b/lib/parsetools/doc/src/Makefile
index a4d7d4381b..bbf84c9c06 100644
--- a/lib/parsetools/doc/src/Makefile
+++ b/lib/parsetools/doc/src/Makefile
@@ -43,6 +43,8 @@ XML_FILES = \
 	$(BOOK_FILES) $(XML_CHAPTER_FILES) \
 	$(XML_PART_FILES) $(XML_REF3_FILES) $(XML_APPLICATION_FILES)
 
+TOP_SPECS_FILE = specs.xml
+
 IMAGE_FILES =
 
 XML_HTML_FILES = \
diff --git a/lib/parsetools/doc/src/leex.xml b/lib/parsetools/doc/src/leex.xml
index 9bfc5cf0af..1de5b94eea 100644
--- a/lib/parsetools/doc/src/leex.xml
+++ b/lib/parsetools/doc/src/leex.xml
@@ -4,7 +4,7 @@
 <erlref>
 <header>
 <copyright>
- <year>2009</year><year>2019</year>
+ <year>2009</year><year>2020</year>
 <holder>Ericsson AB. All Rights Reserved.</holder>
 </copyright>
 <legalnotice>
@@ -29,32 +29,27 @@
 <note>The Leex module should be considered experimental
 as it will be subject to changes in future releases.</note>
 </description>
- <section>
- <title>DATA TYPES</title>
- <code type="none">
-ErrorInfo = {ErrorLine,module(),error_descriptor()}
-ErrorLine = integer()
-Token = tuple()</code>
- </section>
+
+ <datatypes>
+ <datatype>
+ <name name="error_info"></name>
+ <desc>The standard <c>error_info()</c> structure that is returned
+ from all I/O modules. <c><anno>ErrorDescriptor</anno></c> is formatable
+ by <seemfa marker="#format_error/1"><c>format_error/1</c></seemfa>.
+ </desc>
+ </datatype>
+ </datatypes>
+
 <funcs>
 <func>
- <name since="">file(FileName) -> LeexRet</name>
- <name since="OTP R16B02">file(FileName, Options) -> LeexRet</name>
+ <name name="file" arity="1" since=""/>
+ <name name="file" arity="2" since="OTP R16B02"/>
 <fsummary>Generate a lexical analyzer</fsummary>
- <type>
- <v>FileName = filename()</v>
- <v>Options = Option | [Option]</v>
- <v>Option =&nbsp;-&nbsp;see below&nbsp;-</v>
- <v>LeexRet = {ok, Scannerfile}
- | {ok, Scannerfile, Warnings}
- | error
- | {error, Errors, Warnings}</v>
- <v>Scannerfile = filename()</v>
- <v>Warnings = Errors = [{filename(), [ErrorInfo]}]</v>
- <v>ErrorInfo = {ErrorLine, module(), Reason}</v>
- <v>ErrorLine = integer()</v>
- <v>Reason =&nbsp;-&nbsp;formatable by format_error/1&nbsp;-</v>
- </type>
+ <type name="leex_ret"/>
+ <type name="ok_ret"/>
+ <type name="error_ret"/>
+ <type name="errors"/>
+ <type name="warnings"/>
 <desc>
 Generates a lexical analyzer from the definition in the input
 file. The input file has the extension <c>.xrl</c>. This is
@@ -68,72 +63,71 @@ Token = tuple()</code>
 description of the DFA in a format which can be viewed with
 Graphviz, <c>www.graphviz.com</c>.
 </item>
- <tag><c>{includefile,Includefile}</c></tag>
+ <tag><c>{includefile,<anno>Includefile</anno>}</c></tag>
 <item>Uses a specific or customised prologue file
 instead of default
 <c>lib/parsetools/include/leexinc.hrl</c> which is
 otherwise included.
 </item>
- <tag><c>{report_errors, bool()}</c></tag>
+ <tag><c>{report_errors, boolean()}</c></tag>
 <item>Causes errors to be printed as they occur. Default is
 <c>true</c>.
 </item>
- <tag><c>{report_warnings, bool()}</c></tag>
+ <tag><c>{report_warnings, boolean()}</c></tag>
 <item>Causes warnings to be printed as they occur. Default is
 <c>true</c>.
 </item>
- <tag><c>warnings_as_errors</c></tag>
- <item>
- Causes warnings to be treated as errors.
- </item>
- <tag><c>{report, bool()}</c></tag>
+ <tag><c>{report, boolean()}</c></tag>
 <item>This is a short form for both <c>report_errors</c> and
 <c>report_warnings</c>.
 </item>
- <tag><c>{return_errors, bool()}</c></tag>
- <item>If this flag is set, <c>{error, Errors, Warnings}</c>
+ <tag><c>{return_errors, boolean()}</c></tag>
+ <item>If this flag is set,
+	 <c>{error, <anno>Errors</anno>, <anno>Warnings</anno>}</c>
 is returned when there are errors. Default is <c>false</c>.
 </item>
- <tag><c>{return_warnings, bool()}</c></tag>
+ <tag><c>{return_warnings, boolean()}</c></tag>
 <item>If this flag is set, an extra field containing
- <c>Warnings</c> is added to the tuple returned upon
+ <c><anno>Warnings</anno></c> is added to the tuple returned upon
 success. Default is <c>false</c>.
 </item>
- <tag><c>{return, bool()}</c></tag>
+ <tag><c>{return, boolean()}</c></tag>
 <item>This is a short form for both <c>return_errors</c> and
 <c>return_warnings</c>.
 </item>
- <tag><c>{scannerfile, Scannerfile}</c></tag>
- <item><c>Scannerfile</c> is the name of the file that
+ <tag><c>{scannerfile, <anno>Scannerfile</anno>}</c></tag>
+ <item><c><anno>Scannerfile</anno></c> is the name of the file that
 will contain the Erlang scanner code that is generated.
 The default (<c>""</c>) is to add the extension
- <c>.erl</c> to <c>FileName</c> stripped of the
+ <c>.erl</c> to <c><anno>FileName</anno></c> stripped of the
 <c>.xrl</c> extension.
 </item>
- <tag><c>{verbose, bool()}</c></tag>
+ <tag><c>{verbose, boolean()}</c></tag>
 <item>Outputs information from parsing the input file and
 generating the internal tables.
 </item>
+ <tag><c>{warnings_as_errors, boolean()}</c></tag>
+ <item>
+ Causes warnings to be treated as errors.
+ </item>
 </taglist>
 Any of the Boolean options can be set to <c>true</c> by 
 stating the name of the option. For example, <c>verbose</c>
 is equivalent to <c>{verbose, true}</c>.
 Leex will add the extension <c>.hrl</c> to the 
- <c>Includefile</c> name and the extension <c>.erl</c> to the
- <c>Scannerfile</c> name, unless the extension is already
+ <c><anno>Includefile</anno></c> name and the extension <c>.erl</c> to the
+ <c><anno>Scannerfile</anno></c> name, unless the extension is already
 there.
 </desc>
 </func>
 <func>
- <name since="">format_error(ErrorInfo) -> Chars</name>
- <fsummary>Return an English description of a an error tuple.</fsummary>
- <type>
- <v>Chars = [char() | Chars]</v>
- </type>
+ <name name="format_error" arity="1" since=""/>
+ <fsummary>Return an English description of a an error reason.</fsummary>
 <desc>
- Returns a string which describes the error
- <c>ErrorInfo</c> returned when there is an error in a
- regular expression.
+ Returns a descriptive string in English of an error reason
+ <c><anno>ErrorDescriptor</anno></c> returned by
+	<seemfa marker="#file/1"><c>leex:file/1,2</c></seemfa>
+	when there is an error in a regular expression.
 </desc>
 </func>
 </funcs>
@@ -154,7 +148,7 @@ Token = tuple()</code>
 <v>String = string()</v>
 <v>StringRet = {ok,Tokens,EndLine} | ErrorInfo</v>
 <v>Tokens = [Token]</v>
- <v>EndLine = StartLine = integer()</v>
+ <v>EndLine = StartLine = erl_anno:line()</v>
 </type>
 <desc>
 Scans <c>String</c> and returns all the tokens in it, or an
@@ -178,7 +172,7 @@ Token = tuple()</code>
 <v>TokenRet = {ok, Token, EndLine} 
 | {eof, EndLine}
 | ErrorInfo</v>
- <v>StartLine = EndLine = integer()</v>
+ <v>StartLine = EndLine = erl_anno:line()</v>
 </type>
 <desc>
 This is a re-entrant call to try and scan one token from
@@ -214,7 +208,7 @@ io:request(InFile, {get_until,unicode,Prompt,Module,token,[Line]})
 | {eof, EndLine}
 | ErrorInfo</v>
 <v>Tokens = [Token]</v>
- <v>StartLine = EndLine = integer()</v>
+ <v>StartLine = EndLine = erl_anno:line()</v>
 </type>
 <desc>
 This is a re-entrant call to try and scan tokens from
diff --git a/lib/parsetools/doc/src/specs.xml b/lib/parsetools/doc/src/specs.xml
new file mode 100644
index 0000000000..21f8b1b25b
--- /dev/null
+++ b/lib/parsetools/doc/src/specs.xml
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<specs xmlns:xi="http://www.w3.org/2001/XInclude">
+ <xi:include href="../specs/specs_leex.xml"/>
+ <xi:include href="../specs/specs_yecc.xml"/>
+</specs>
diff --git a/lib/parsetools/doc/src/yecc.xml b/lib/parsetools/doc/src/yecc.xml
index 67a2c95c25..a956cff872 100644
--- a/lib/parsetools/doc/src/yecc.xml
+++ b/lib/parsetools/doc/src/yecc.xml
@@ -44,108 +44,112 @@
 parser generator, and the principle and problems of LALR parsing
 with finite look-ahead.
 </description>
+
+ <datatypes>
+ <datatype>
+ <name name="error_info"></name>
+ <desc>The standard <c>error_info()</c> structure that is returned
+ from all I/O modules. <c><anno>ErrorDescriptor</anno></c> is formatable
+ by <seemfa marker="#format_error/1"><c>format_error/1</c></seemfa>.
+ </desc>
+ </datatype>
+ </datatypes>
+
 <funcs>
 <func>
- <name since="">file(Grammarfile [, Options]) -> YeccRet</name>
+ <name name="file" arity="1" since=""/>
+ <name name="file" arity="2" since=""/>
 <fsummary>Give information about resolved and unresolved parse action conflicts.</fsummary>
- <type>
- <v>Grammarfile = filename()</v>
- <v>Options = Option | [Option]</v>
- <v>Option =&nbsp;-&nbsp;see below&nbsp;-</v>
- <v>YeccRet = {ok, Parserfile} | {ok, Parserfile, Warnings} | error | {error, Errors, Warnings}</v>
- <v>Parserfile = filename()</v>
- <v>Warnings = Errors = [{filename(), [ErrorInfo]}]</v>
- <v>ErrorInfo = {ErrorLine, module(), Reason}</v>
- <v>ErrorLine = integer()</v>
- <v>Reason =&nbsp;-&nbsp;formatable by format_error/1&nbsp;-</v>
- </type>
+ <type name="yecc_ret"/>
+ <type name="ok_ret"/>
+ <type name="error_ret"/>
+ <type name="errors"/>
+ <type name="warnings"/>
 <desc>
- <c>Grammarfile</c> is the file of declarations and grammar
+ <c><anno>Grammarfile</anno></c> is the file of declarations and grammar
 rules. Returns <c>ok</c> upon success, or <c>error</c> if
 there are errors. An Erlang file containing the parser is
 created if there are no errors. The options are:
 
 <taglist>
- <tag><c>{parserfile, Parserfile}</c>.</tag>
- <item><c>Parserfile</c> is the name of the file that will
- contain the Erlang parser code that is generated. The
- default (<c>""</c>) is to add the extension <c>.erl</c>
- to <c>Grammarfile</c> stripped of the <c>.yrl</c>
- extension.
- </item>
- <tag><c>{includefile, Includefile}</c>.</tag>
- <item>Indicates a customized prologue file which the user
+ <tag><c>{includefile, <anno>Includefile</anno>}</c>.</tag>
+ <item>Indicates a customized prologue file which the user
 may want to use instead of the default file
 <c>lib/parsetools/include/yeccpre.hrl</c> which is
 otherwise included at the beginning of the resulting
- parser file. N.B. The <c>Includefile</c> is
+ parser file. N.B. The <c><anno>Includefile</anno></c> is
 included 'as is' in the parser file, so it must not have a
 module declaration of its own, and it should not be
 compiled. It must, however, contain the necessary export
- declarations. The default is indicated by <c>""</c>.
+ declarations. The default is indicated by <c>""</c>.
 </item>
- <tag><c>{report_errors, bool()}</c>.</tag>
- <item>Causes errors to be printed as they occur. Default is
- <c>true</c>.
+ <tag><c>{parserfile, <anno>Parserfile</anno>}</c>.</tag>
+ <item><c><anno>Parserfile</anno></c> is the name of the file that will
+ contain the Erlang parser code that is generated. The
+ default (<c>""</c>) is to add the extension <c>.erl</c>
+ to <c><anno>Grammarfile</anno></c> stripped of the <c>.yrl</c>
+ extension.
 </item>
- <tag><c>{report_warnings, bool()}</c>.</tag>
- <item>Causes warnings to be printed as they occur. Default is
- <c>true</c>.
+ <tag><c>{report_errors, boolean()}</c>.</tag>
+ <item>Causes errors to be printed as they occur. Default is
+ <c>true</c>.
 </item>
- <tag><c>{report, bool()}</c>.</tag>
- <item>This is a short form for both <c>report_errors</c> and
- <c>report_warnings</c>.
+ <tag><c>{report_warnings, boolean()}</c>.</tag>
+ <item>Causes warnings to be printed as they occur. Default is
+ <c>true</c>.
 </item>
- <tag><c>warnings_as_errors</c></tag>
- <item>
- Causes warnings to be treated as errors.
+ <tag><c>{report, boolean()}</c>.</tag>
+ <item>This is a short form for both <c>report_errors</c> and
+ <c>report_warnings</c>.
 </item>
- <tag><c>{return_errors, bool()}</c>.</tag>
- <item>If this flag is set, <c>{error, Errors, Warnings}</c>
+ <tag><c>{return_errors, boolean()}</c>.</tag>
+ <item>If this flag is set,
+	 <c>{error, <anno>Errors</anno>, <anno>Warnings</anno>}</c>
 is returned when there are errors. Default is
- <c>false</c>.
+ <c>false</c>.
 </item>
- <tag><c>{return_warnings, bool()}</c>.</tag>
- <item>If this flag is set, an extra field containing
- <c>Warnings</c> is added to the tuple returned upon
- success. Default is <c>false</c>.
+ <tag><c>{return_warnings, boolean()}</c>.</tag>
+ <item>If this flag is set, an extra field containing
+ <c><anno>Warnings</anno></c> is added to the tuple returned upon
+ success. Default is <c>false</c>.
 </item>
- <tag><c>{return, bool()}</c>.</tag>
- <item>This is a short form for both <c>return_errors</c> and
- <c>return_warnings</c>.
+ <tag><c>{return, boolean()}</c>.</tag>
+ <item>This is a short form for both <c>return_errors</c> and
+ <c>return_warnings</c>.
 </item>
- <tag><c>{verbose, bool()}</c>. </tag>
- <item>Determines whether the parser generator should give
+ <tag><c>{verbose, boolean()}</c>. </tag>
+ <item>Determines whether the parser generator should give
 full information about resolved and unresolved parse
 action conflicts (<c>true</c>), or only about those
 conflicts that prevent a parser from being generated from
- the input grammar (<c>false</c>, the default).
+ the input grammar (<c>false</c>, the default).
+ </item>
+ <tag><c>{warnings_as_errors, boolean()}</c></tag>
+ <item>
+ Causes warnings to be treated as errors.
 </item>
 </taglist>
 Any of the Boolean options can be set to <c>true</c> by 
 stating the name of the option. For example, <c>verbose</c>
 is equivalent to <c>{verbose, true}</c>.
 
- The value of the <c>Parserfile</c> option stripped of the
+ The value of the <c><anno>Parserfile</anno></c> option stripped of the
 <c>.erl</c> extension is used by Yecc as the module name of
 the generated parser file.
 Yecc will add the extension <c>.yrl</c> to the
- <c>Grammarfile</c> name, the extension <c>.hrl</c> to the
- <c>Includefile</c> name, and the extension <c>.erl</c> to
- the <c>Parserfile</c> name, unless the extension is already
+ <c><anno>Grammarfile</anno></c> name, the extension <c>.hrl</c> to the
+ <c><anno>Includefile</anno></c> name, and the extension <c>.erl</c> to
+ the <c><anno>Parserfile</anno></c> name, unless the extension is already
 there.
 </desc>
 </func>
 <func>
- <name since="">format_error(Reason) -> Chars</name>
- <fsummary>Return an English description of a an error tuple.</fsummary>
- <type>
- <v>Reason =&nbsp;-&nbsp;as returned by yecc:file/1,2&nbsp;-</v>
- <v>Chars = [char() | Chars]</v>
- </type>
+ <name name="format_error" arity="1" since=""/>
+ <fsummary>Return an English description of a an error reason.</fsummary>
 <desc>
- Returns a descriptive string in English of an error tuple
- returned by <c>yecc:file/1,2</c>. This function is mainly
+ Returns a descriptive string in English of an error reason
+ <c><anno>ErrorDescriptor</anno></c> returned by
+ <c>yecc:file/1,2</c>. This function is mainly
 used by the compiler invoking Yecc.
 </desc>
 </func>
diff --git a/lib/parsetools/src/leex.erl b/lib/parsetools/src/leex.erl
index 8a4a5e8d86..f60ad76175 100644
--- a/lib/parsetools/src/leex.erl
+++ b/lib/parsetools/src/leex.erl
@@ -89,11 +89,40 @@ compile(Input0, Output0,
 error
 end.
 
-%% file(File) -> ok | error.
-%% file(File, Options) -> ok | error.
+-type error_info() :: {erl_anno:line() | 'none',
+ module(), ErrorDescriptor :: term()}.
+-type errors() :: [{file:filename(), [error_info()]}].
+-type warnings() :: [{file:filename(), [error_info()]}].
+-type ok_ret() :: {'ok', Scannerfile :: file:filename()}
+ | {'ok', Scannerfile :: file:filename(), warnings()}.
+-type error_ret() :: 'error'
+ | {'error', Errors :: errors(), Warnings :: warnings()}.
+-type leex_ret() :: ok_ret() | error_ret().
+
+-spec file(FileName) -> leex_ret() when
+ FileName :: file:filename().
 
 file(File) -> file(File, []).
 
+-spec file(FileName, Options) -> leex_ret() when
+ FileName :: file:filename(),
+ Options :: Option | [Option],
+ Option :: {'dfa_graph', boolean()}
+ | {'includefile', Includefile :: file:filename()}
+ | {'report_errors', boolean()}
+ | {'report_warnings', boolean()}
+ | {'report', boolean()}
+ | {'return_errors', boolean()}
+ | {'return_warnings', boolean()}
+ | {'return', boolean()}
+ | {'scannerfile', Scannerfile :: file:filename()}
+ | {'verbose', boolean()}
+ | {'warnings_as_errors', boolean()}
+ | 'dfa_graph'
+ | 'report_errors' | 'report_warnings' | 'report'
+ | 'return_errors' | 'return_warnings' | 'return'
+ | 'verbose' | 'warnings_as_errors'.
+
 file(File, Opts0) ->
 case is_filename(File) of
 no -> erlang:error(badarg, [File,Opts0]);
@@ -125,6 +154,9 @@ file(File, Opts0) ->
 end,
 leex_ret(St). 
 
+-spec format_error(ErrorDescriptor) -> io_lib:chars() when
+ ErrorDescriptor :: term().
+
 format_error({file_error, Reason}) ->
 io_lib:fwrite("~ts",[file:format_error(Reason)]);
 format_error(missing_defs) -> "missing Definitions";
diff --git a/lib/parsetools/src/yecc.erl b/lib/parsetools/src/yecc.erl
index f44b1da861..6e132c7660 100644
--- a/lib/parsetools/src/yecc.erl
+++ b/lib/parsetools/src/yecc.erl
@@ -151,6 +151,9 @@ compile(Input0, Output0,
 error
 end.
 
+-spec format_error(ErrorDescriptor) -> io_lib:chars() when
+ ErrorDescriptor :: term().
+
 format_error(bad_declaration) ->
 io_lib:fwrite("unknown or bad declaration, ignored", []);
 format_error({bad_expect, SymName}) ->
@@ -232,8 +235,38 @@ format_error({bad_symbol, String}) ->
 format_error(cannot_parse) ->
 io_lib:fwrite("cannot parse; possibly encoding mismatch", []).
 
-file(File) ->
- file(File, [report_errors, report_warnings]).
+-type error_info() :: {erl_anno:line() | 'none',
+ module(), ErrorDescriptor :: term()}.
+-type errors() :: [{file:filename(), [error_info()]}].
+-type warnings() :: [{file:filename(), [error_info()]}].
+-type ok_ret() :: {'ok', Parserfile :: file:filename()}
+ | {'ok', Parserfile :: file:filename(), warnings()}.
+-type error_ret() :: 'error'
+ | {'error', Errors :: errors(), Warnings :: warnings()}.
+-type yecc_ret() :: ok_ret() | error_ret().
+
+-spec file(FileName) -> yecc_ret() when
+ FileName :: file:filename().
+
+file(GrammarFile) ->
+ file(GrammarFile, [report_errors, report_warnings]).
+
+-spec file(Grammarfile, Options) -> yecc_ret() when
+ Grammarfile :: file:filename(),
+ Options :: Option | [Option],
+ Option :: {'includefile', Includefile :: file:filename()}
+ | {'report_errors', boolean()}
+ | {'report_warnings', boolean()}
+ | {'report', boolean()}
+ | {'return_errors', boolean()}
+ | {'return_warnings', boolean()}
+ | {'return', boolean()}
+ | {'parserfile', Parserfile :: file:filename()}
+ | {'verbose', boolean()}
+ | {'warnings_as_errors', boolean()}
+ | 'report_errors' | 'report_warnings' | 'report'
+ | 'return_errors' | 'return_warnings' | 'return'
+ | 'verbose' | 'warnings_as_errors'.
 
 file(File, Options) ->
 case is_filename(File) of
-- 
2.26.2

Places

File 0189-parsetools-Use-types-and-specs-for-documentation.patch of Package erlang (Revision 1e94e72e3f4fed1ca9cd5c2fd777ed02)

Places