r

Use Erlang specs and types for documentation

1 files changed, 59 insertions, 93 deletions

diff --git a/lib/stdlib/doc/src/regexp.xml b/lib/stdlib/doc/src/regexp.xml
index 8c4191c88f..35d8e1c3f8 100644
--- a/lib/stdlib/doc/src/regexp.xml
+++ b/lib/stdlib/doc/src/regexp.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2009</year>
+      <year>1996</year><year>2011</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -40,176 +40,150 @@
     <p>This module contains functions for regular expression
       matching and substitution.</p>
   </description>
+  <datatypes>
+    <datatype>
+      <name name="errordesc"></name>
+    </datatype>
+    <datatype>
+      <name name="regexp"></name>
+      <desc><p>Internal representation of a regular expression.</p></desc>
+    </datatype>
+  </datatypes>
   <funcs>
     <func>
-      <name>match(String, RegExp) -> MatchRes</name>
+      <name name="match" arity="2"/>
       <fsummary>Match a regular expression</fsummary>
-      <type>
-        <v>String = RegExp = string()</v>
-        <v>MatchRes = {match,Start,Length} | nomatch | {error,errordesc()}</v>
-        <v>Start = Length = integer()</v>
-      </type>
       <desc>
-        <p>Finds the first, longest match of the regular expression <c>RegExp</c> in <c>String</c>. This function searches for the longest possible match and returns the first one found if there are several expressions of the same length. It returns as follows:</p>
+        <p>Finds the first, longest match of the regular expression <c><anno>RegExp</anno></c> in <c><anno>String</anno></c>. This function searches for the longest possible match and returns the first one found if there are several expressions of the same length. It returns as follows:</p>
         <taglist>
-          <tag><c>{match,Start,Length}</c></tag>
+          <tag><c>{match,<anno>Start</anno>,<anno>Length</anno>}</c></tag>
           <item>
-            <p>if the match succeeded. <c>Start</c> is the starting
-              position of the match, and <c>Length</c> is the length of
+            <p>if the match succeeded. <c><anno>Start</anno></c> is the starting
+              position of the match, and <c><anno>Length</anno></c> is the length of
               the matching string.</p>
           </item>
           <tag><c>nomatch</c></tag>
           <item>
             <p>if there were no matching characters.</p>
           </item>
-          <tag><c>{error,Error}</c></tag>
+          <tag><c>{error,<anno>Error</anno>}</c></tag>
           <item>
-            <p>if there was an error in <c>RegExp</c>.</p>
+            <p>if there was an error in <c><anno>RegExp</anno></c>.</p>
           </item>
         </taglist>
       </desc>
     </func>
     <func>
-      <name>first_match(String, RegExp) -> MatchRes</name>
+      <name name="first_match" arity="2"/>
       <fsummary>Match a regular expression</fsummary>
-      <type>
-        <v>String = RegExp = string()</v>
-        <v>MatchRes = {match,Start,Length} | nomatch | {error,errordesc()}</v>
-        <v>Start = Length = integer()</v>
-      </type>
       <desc>
-        <p>Finds the first match of the regular expression <c>RegExp</c> in <c>String</c>. This call is
+        <p>Finds the first match of the regular expression <c><anno>RegExp</anno></c> in <c><anno>String</anno></c>. This call is
           usually faster than <c>match</c> and it is also a useful way to ascertain that a match exists. It returns as follows:</p>
         <taglist>
-          <tag><c>{match,Start,Length}</c></tag>
+          <tag><c>{match,<anno>Start</anno>,<anno>Length</anno>}</c></tag>
           <item>
-            <p>if the match succeeded. <c>Start</c> is the starting
-              position of the match and <c>Length</c> is the length of
+            <p>if the match succeeded. <c><anno>Start</anno></c> is the starting
+              position of the match and <c><anno>Length</anno></c> is the length of
               the matching string.</p>
           </item>
           <tag><c>nomatch</c></tag>
           <item>
             <p>if there were no matching characters.</p>
           </item>
-          <tag><c>{error,Error}</c></tag>
+          <tag><c>{error,<anno>Error</anno>}</c></tag>
           <item>
-            <p>if there was an error in <c>RegExp</c>.</p>
+            <p>if there was an error in <c><anno>RegExp</anno></c>.</p>
           </item>
         </taglist>
       </desc>
     </func>
     <func>
-      <name>matches(String, RegExp) -> MatchRes</name>
+      <name name="matches" arity="2"/>
       <fsummary>Match a regular expression</fsummary>
-      <type>
-        <v>String = RegExp = string()</v>
-        <v>MatchRes = {match, Matches} | {error, errordesc()}</v>
-        <v>Matches = list()</v>
-      </type>
       <desc>
         <p>Finds all non-overlapping matches of the
-          expression <c>RegExp</c> in <c>String</c>.
+          expression <c><anno>RegExp</anno></c> in <c><anno>String</anno></c>.
           It returns as follows:</p>
         <taglist>
-          <tag><c>{match, Matches}</c></tag>
+          <tag><c>{match, <anno>Matches</anno>}</c></tag>
           <item>
             <p>if the regular expression was correct.
-              The list will be empty if there was no match. Each element in the list looks like <c>{Start, Length}</c>, where <c>Start</c> is the starting position of the match, and <c>Length</c> is the length of the matching string.</p>
+              The list will be empty if there was no match. Each element in the list looks like <c>{<anno>Start</anno>, <anno>Length</anno>}</c>, where <c><anno>Start</anno></c> is the starting position of the match, and <c><anno>Length</anno></c> is the length of the matching string.</p>
           </item>
-          <tag><c>{error,Error}</c></tag>
+          <tag><c>{error,<anno>Error</anno>}</c></tag>
           <item>
-            <p>if there was an error in <c>RegExp</c>.</p>
+            <p>if there was an error in <c><anno>RegExp</anno></c>.</p>
           </item>
         </taglist>
       </desc>
     </func>
     <func>
-      <name>sub(String, RegExp, New) -> SubRes</name>
+      <name name="sub" arity="3"/>
       <fsummary>Substitute the first occurrence of a regular expression</fsummary>
-      <type>
-        <v>String = RegExp = New = string()</v>
-        <v>SubRes = {ok,NewString,RepCount} | {error,errordesc()}</v>
-        <v>RepCount = integer()</v>
-      </type>
       <desc>
-        <p>Substitutes the first occurrence of a substring matching <c>RegExp</c> in <c>String</c> with the string <c>New</c>. A <c><![CDATA[&]]></c> in the string <c>New</c> is replaced by the matched substring of <c>String</c>.  <c><![CDATA[\&]]></c> puts a literal <c><![CDATA[&]]></c> into the replacement string. It returns as follows:</p>
+        <p>Substitutes the first occurrence of a substring matching <c><anno>RegExp</anno></c> in <c><anno>String</anno></c> with the string <c><anno>New</anno></c>. A <c><![CDATA[&]]></c> in the string <c><anno>New</anno></c> is replaced by the matched substring of <c><anno>String</anno></c>.  <c><![CDATA[\&]]></c> puts a literal <c><![CDATA[&]]></c> into the replacement string. It returns as follows:</p>
         <taglist>
-          <tag><c>{ok,NewString,RepCount}</c></tag>
+          <tag><c>{ok,<anno>NewString</anno>,<anno>RepCount</anno>}</c></tag>
           <item>
-            <p>if <c>RegExp</c> is correct. <c>RepCount</c> is the number of replacements which have been made
+            <p>if <c><anno>RegExp</anno></c> is correct. <c><anno>RepCount</anno></c> is the number of replacements which have been made
               (this will be either 0 or 1).</p>
           </item>
-          <tag><c>{error, Error}</c></tag>
+          <tag><c>{error, <anno>Error</anno>}</c></tag>
           <item>
-            <p>if there is an error in <c>RegExp</c>.</p>
+            <p>if there is an error in <c><anno>RegExp</anno></c>.</p>
           </item>
         </taglist>
       </desc>
     </func>
     <func>
-      <name>gsub(String, RegExp, New) -> SubRes</name>
+      <name name="gsub" arity="3"/>
       <fsummary>Substitute all occurrences of a regular expression</fsummary>
-      <type>
-        <v>String = RegExp = New = string()</v>
-        <v>SubRes = {ok,NewString,RepCount} | {error,errordesc()}</v>
-        <v>RepCount = integer()</v>
-      </type>
       <desc>
         <p>The same as <c>sub</c>, except that all non-overlapping
           occurrences of a substring matching
-          <c>RegExp</c> in <c>String</c> are replaced by the string <c>New</c>. It returns:</p>
+          <c><anno>RegExp</anno></c> in <c><anno>String</anno></c> are replaced by the string <c><anno>New</anno></c>. It returns:</p>
         <taglist>
-          <tag><c>{ok,NewString,RepCount}</c></tag>
+          <tag><c>{ok,<anno>NewString</anno>,<anno>RepCount</anno>}</c></tag>
           <item>
-            <p>if <c>RegExp</c> is correct. <c>RepCount</c> is the number of replacements which have been made.</p>
+            <p>if <c><anno>RegExp</anno></c> is correct. <c><anno>RepCount</anno></c> is the number of replacements which have been made.</p>
           </item>
-          <tag><c>{error, Error}</c></tag>
+          <tag><c>{error, <anno>Error</anno>}</c></tag>
           <item>
-            <p>if there is an error in <c>RegExp</c>.</p>
+            <p>if there is an error in <c><anno>RegExp</anno></c>.</p>
           </item>
         </taglist>
       </desc>
     </func>
     <func>
-      <name>split(String, RegExp) -> SplitRes</name>
+      <name name="split" arity="2"/>
       <fsummary>Split a string into fields</fsummary>
-      <type>
-        <v>String = RegExp = string()</v>
-        <v>SubRes = {ok,FieldList} | {error,errordesc()}</v>
-        <v>Fieldlist = [string()]</v>
-      </type>
       <desc>
-        <p><c>String</c> is split into fields (sub-strings) by the
-          regular expression <c>RegExp</c>.</p>
+        <p><c><anno>String</anno></c> is split into fields (sub-strings) by the
+          regular expression <c><anno>RegExp</anno></c>.</p>
         <p>If the separator expression is <c>" "</c> (a single space),
           then the fields are separated by blanks and/or tabs and
           leading and trailing blanks and tabs are discarded. For all
           other values of the separator, leading and trailing blanks
           and tabs are not discarded. It returns:</p>
         <taglist>
-          <tag><c>{ok, FieldList}</c></tag>
+          <tag><c>{ok, <anno>FieldList</anno>}</c></tag>
           <item>
             <p>to indicate that the string has been split up into the fields of
-              <c>FieldList</c>.</p>
+              <c><anno>FieldList</anno></c>.</p>
           </item>
-          <tag><c>{error, Error}</c></tag>
+          <tag><c>{error, <anno>Error</anno>}</c></tag>
           <item>
-            <p>if there is an error in <c>RegExp</c>.</p>
+            <p>if there is an error in <c><anno>RegExp</anno></c>.</p>
           </item>
         </taglist>
       </desc>
     </func>
     <func>
-      <name>sh_to_awk(ShRegExp) -> AwkRegExp</name>
+      <name name="sh_to_awk" arity="1"/>
       <fsummary>Convert an <c>sh</c>regular expression into an <c>AWK</c>one</fsummary>
-      <type>
-        <v>ShRegExp AwkRegExp = string()</v>
-        <v>SubRes = {ok,NewString,RepCount} | {error,errordesc()}</v>
-        <v>RepCount = integer()</v>
-      </type>
       <desc>
         <p>Converts the <c>sh</c> type regular expression
-          <c>ShRegExp</c> into a full <c>AWK</c> regular
+          <c><anno>ShRegExp</anno></c> into a full <c>AWK</c> regular
           expression. Returns the converted regular expression
           string. <c>sh</c> expressions are used in the shell for
           matching file names and have the following special
@@ -236,40 +210,32 @@
       </desc>
     </func>
     <func>
-      <name>parse(RegExp) -> ParseRes</name>
+      <name name="parse" arity="1"/>
       <fsummary>Parse a regular expression</fsummary>
-      <type>
-        <v>RegExp = string()</v>
-        <v>ParseRes = {ok,RE} | {error,errordesc()}</v>
-      </type>
       <desc>
-        <p>Parses the regular expression <c>RegExp</c> and builds the
+        <p>Parses the regular expression <c><anno>RegExp</anno></c> and builds the
           internal representation used in the other regular expression
           functions. Such representations can be used in all of the
           other functions instead of a regular expression string. This
           is more efficient when the same regular expression is used
           in many strings. It returns:</p>
         <taglist>
-          <tag><c>{ok, RE}</c>if <c>RegExp</c>is correct and <c>RE</c>is the internal representation.</tag>
+          <tag><c>{ok, <anno>RE</anno>}</c></tag>
           <item>
-            <p></p>
+            <p>if <c>RegExp</c> is correct and <c><anno>RE</anno></c> is the internal representation.</p>
           </item>
-          <tag><c>{error, Error}</c>if there is an error in <c>RegExpString</c>.</tag>
+          <tag><c>{error, <anno>Error</anno>}</c></tag>
           <item>
-            <p></p>
+            <p>if there is an error in <c><anno>RegExp</anno></c>.</p>
           </item>
         </taglist>
       </desc>
     </func>
     <func>
-      <name>format_error(ErrorDescriptor) -> Chars</name>
+      <name name="format_error" arity="1"/>
       <fsummary>Format an error descriptor</fsummary>
-      <type>
-        <v>ErrorDescriptor = errordesc()</v>
-        <v>Chars = [char() | Chars]</v>
-      </type>
       <desc>
-        <p>Returns a string which describes the error <c>ErrorDescriptor</c>
+        <p>Returns a string which describes the error <c><anno>ErrorDescriptor</anno></c>
           returned when there is an error in a regular expression.</p>
       </desc>
     </func>