r

Use Erlang specs and types for documentation

1 files changed, 59 insertions, 63 deletions

diff --git a/lib/stdlib/doc/src/erl_parse.xml b/lib/stdlib/doc/src/erl_parse.xml
index 18b592deea..bafc2e0746 100644
--- a/lib/stdlib/doc/src/erl_parse.xml
+++ b/lib/stdlib/doc/src/erl_parse.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2010</year>
+      <year>1996</year><year>2011</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -36,31 +36,51 @@
   <description>
     <p>This module is the basic Erlang parser which converts tokens into
       the abstract form of either forms (i.e., top-level constructs),
-      expressions, or terms. The Abstract Format is described in the ERTS
-      User's Guide.
+      expressions, or terms. The Abstract Format is described in the
+      <seealso marker="erts:absform">ERTS User's Guide</seealso>.
       Note that a token list must end with the <em>dot</em> token in order
       to be acceptable to the parse functions (see <seealso marker="erl_scan">erl_scan(3)</seealso>).</p>
   </description>
+  <datatypes>
+    <datatype>
+      <name name="abstract_clause"></name>
+      <desc><p>Parse tree for Erlang clause.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="abstract_expr"></name>
+      <desc><p>Parse tree for Erlang expression.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="abstract_form"></name>
+      <desc><p>Parse tree for Erlang form.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="error_description"></name>
+    </datatype>
+    <datatype>
+      <name name="error_info"></name>
+    </datatype>
+    <datatype>
+      <name name="token"></name>
+    </datatype>
+  </datatypes>
   <funcs>
     <func>
-      <name>parse_form(Tokens) -> {ok, AbsForm} | {error, ErrorInfo}</name>
+      <name name="parse_form" arity="1"/>
       <fsummary>Parse an Erlang form</fsummary>
-      <type>
-        <v>Tokens = [Token]</v>
-        <v>Token = {Tag,Line} | {Tag,Line,term()}</v>
-        <v>Tag = atom()</v>
-        <v>AbsForm = term()</v>
-        <v>ErrorInfo = see section Error Information below.</v>
-      </type>
       <desc>
-        <p>This function parses <c>Tokens</c> as if it were a form. It returns:</p>
+        <p>This function parses <c><anno>Tokens</anno></c> as if it were
+          a form. It returns:</p>
         <taglist>
-          <tag><c>{ok, AbsForm}</c></tag>
+          <tag><c>{ok, <anno>AbsForm</anno>}</c></tag>
           <item>
-            <p>The parsing was successful. <c>AbsForm</c> is the
+            <p>The parsing was successful. <c><anno>AbsForm</anno></c> is the
               abstract form of the parsed form.</p>
           </item>
-          <tag><c>{error, ErrorInfo}</c></tag>
+          <tag><c>{error, <anno>ErrorInfo</anno>}</c></tag>
           <item>
             <p>An error occurred.</p>
           </item>
@@ -68,25 +88,18 @@
       </desc>
     </func>
     <func>
-      <name>parse_exprs(Tokens) -> {ok, Expr_list} | {error, ErrorInfo}</name>
+      <name name="parse_exprs" arity="1"/>
       <fsummary>Parse Erlang expressions</fsummary>
-      <type>
-        <v>Tokens = [Token]</v>
-        <v>Token = {Tag,Line} | {Tag,Line,term()}</v>
-        <v>Tag = atom()</v>
-        <v>Expr_list = [AbsExpr]</v>
-        <v>AbsExpr = term()</v>
-        <v>ErrorInfo = see section Error Information below.</v>
-      </type>
       <desc>
-        <p>This function parses <c>Tokens</c> as if it were a list of expressions. It returns:</p>
+        <p>This function parses <c><anno>Tokens</anno></c> as if it were
+          a list of expressions. It returns:</p>
         <taglist>
-          <tag><c>{ok, Expr_list}</c></tag>
+          <tag><c>{ok, <anno>ExprList</anno>}</c></tag>
           <item>
-            <p>The parsing was successful. <c>Expr_list</c> is a
+            <p>The parsing was successful. <c><anno>ExprList</anno></c> is a
               list of the abstract forms of the parsed expressions.</p>
           </item>
-          <tag><c>{error, ErrorInfo}</c></tag>
+          <tag><c>{error, <anno>ErrorInfo</anno>}</c></tag>
           <item>
             <p>An error occurred.</p>
           </item>
@@ -94,21 +107,15 @@
       </desc>
     </func>
     <func>
-      <name>parse_term(Tokens) -> {ok, Term} | {error, ErrorInfo}</name>
+      <name name="parse_term" arity="1"/>
       <fsummary>Parse an Erlang term</fsummary>
-      <type>
-        <v>Tokens = [Token]</v>
-        <v>Token = {Tag,Line} | {Tag,Line,term()}</v>
-        <v>Tag = atom()</v>
-        <v>Term = term()</v>
-        <v>ErrorInfo = see section Error Information below.</v>
-      </type>
       <desc>
-        <p>This function parses <c>Tokens</c> as if it were a term. It returns:</p>
+        <p>This function parses <c><anno>Tokens</anno></c> as if it were
+          a term. It returns:</p>
         <taglist>
-          <tag><c>{ok, Term}</c></tag>
+          <tag><c>{ok, <anno>Term</anno>}</c></tag>
           <item>
-            <p>The parsing was successful. <c>Term</c> is
+            <p>The parsing was successful. <c><anno>Term</anno></c> is
               the Erlang term corresponding to the token list.</p>
           </item>
           <tag><c>{error, ErrorInfo}</c></tag>
@@ -122,7 +129,8 @@
       <name>format_error(ErrorDescriptor) -> Chars</name>
       <fsummary>Format an error descriptor</fsummary>
       <type>
-        <v>ErrorDescriptor = errordesc()</v>
+        <v>ErrorDescriptor = <seealso
+          marker="#type-error_info">error_description()</seealso></v>
         <v>Chars = [char() | Chars]</v>
       </type>
       <desc>
@@ -133,44 +141,32 @@
       </desc>
     </func>
     <func>
-      <name>tokens(AbsTerm) -> Tokens</name>
-      <name>tokens(AbsTerm, MoreTokens) -> Tokens</name>
+      <name name="tokens" arity="1"/>
+      <name name="tokens" arity="2"/>
       <fsummary>Generate a list of tokens for an expression</fsummary>
-      <type>
-        <v>Tokens = MoreTokens = [Token]</v>
-        <v>Token = {Tag,Line} | {Tag,Line,term()}</v>
-        <v>Tag = atom()</v>
-        <v>AbsTerm = term()</v>
-        <v>ErrorInfo = see section Error Information below.</v>
-      </type>
       <desc>
         <p>This function generates a list of tokens representing the abstract
-          form <c>AbsTerm</c> of an expression. Optionally, it appends
-          <c>Moretokens</c>.</p>
+          form <c><anno>AbsTerm</anno></c> of an expression. Optionally, it
+          appends <c><anno>MoreTokens</anno></c>.</p>
       </desc>
     </func>
     <func>
-      <name>normalise(AbsTerm) -> Data</name>
+      <name name="normalise" arity="1"/>
       <fsummary>Convert abstract form to an Erlang term</fsummary>
-      <type>
-        <v>AbsTerm = Data = term()</v>
-      </type>
       <desc>
-        <p>Converts the abstract form <c>AbsTerm</c> of a term into a
+        <p>Converts the abstract form <c><anno>AbsTerm</anno></c> of a
+          term into a
           conventional Erlang data structure (i.e., the term itself).
           This is the inverse of <c>abstract/1</c>.</p>
       </desc>
     </func>
     <func>
-      <name>abstract(Data) -> AbsTerm</name>
+      <name name="abstract" arity="1"/>
       <fsummary>Convert an Erlang term into an abstract form</fsummary>
-      <type>
-        <v>Data = AbsTerm = term()</v>
-      </type>
       <desc>
-        <p>Converts the Erlang data structure <c>Data</c> into an
-          abstract form of type <c>AbsTerm</c>. This is the inverse of
-          <c>normalise/1</c>.</p>
+        <p>Converts the Erlang data structure <c><anno>Data</anno></c> into an
+          abstract form of type <c><anno>AbsTerm</anno></c>.
+          This is the inverse of <c>normalise/1</c>.</p>
       </desc>
     </func>
   </funcs>