OTP-8404: Doc: some corrections and improvements in STDLIB

11 files changed, 75 insertions, 62 deletions

diff --git a/lib/compiler/doc/src/compile.xml b/lib/compiler/doc/src/compile.xml
index daa686bc56..bbd3f1043d 100644
--- a/lib/compiler/doc/src/compile.xml
+++ b/lib/compiler/doc/src/compile.xml
@@ -732,7 +732,7 @@ pi() -> 3.1416.
     <p>A string describing the error is obtained with the following
       call:</p>
     <code>
-apply(Module, format_error, ErrorDescriptor)
+Module:format_error(ErrorDescriptor)
     </code>
   </section>
 
diff --git a/lib/stdlib/doc/src/epp.xml b/lib/stdlib/doc/src/epp.xml
index 455d9dc124..e6b48b270a 100644
--- a/lib/stdlib/doc/src/epp.xml
+++ b/lib/stdlib/doc/src/epp.xml
@@ -4,23 +4,21 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year>
-      <year>2007</year>
-      <holder>Ericsson AB, All Rights Reserved</holder>
+      <year>1996</year><year>2010</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
-  The contents of this file are subject to the Erlang Public License,
-  Version 1.1, (the "License"); you may not use this file except in
-  compliance with the License. You should have received a copy of the
-  Erlang Public License along with this software. If not, it can be
-  retrieved online at http://www.erlang.org/.
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
 
-  Software distributed under the License is distributed on an "AS IS"
-  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
-  the License for the specific language governing rights and limitations
-  under the License.
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
 
-  The Initial Developer of the Original Code is Ericsson AB.
     </legalnotice>
 
     <title>epp</title>
@@ -112,7 +110,7 @@
     <p>A string which describes the error is obtained with the following call:
       </p>
     <code type="none">
-apply(Module, format_error, ErrorDescriptor)    </code>
+    Module:format_error(ErrorDescriptor)    </code>
   </section>
 
   <section>
diff --git a/lib/stdlib/doc/src/erl_lint.xml b/lib/stdlib/doc/src/erl_lint.xml
index e339f484cc..6a7d37765c 100644
--- a/lib/stdlib/doc/src/erl_lint.xml
+++ b/lib/stdlib/doc/src/erl_lint.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2009</year>
+      <year>1996</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,12 +13,12 @@
       compliance with the License. You should have received a copy of the
       Erlang Public License along with this software. If not, it can be
       retrieved online at http://www.erlang.org/.
-    
+
       Software distributed under the License is distributed on an "AS IS"
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-    
+
     </legalnotice>
 
     <title>erl_lint</title>
@@ -147,7 +147,7 @@
     <p>A string which describes the error is obtained with the following call:
       </p>
     <code type="none">
-apply(Module, format_error, ErrorDescriptor)    </code>
+    Module:format_error(ErrorDescriptor)    </code>
   </section>
 
   <section>
diff --git a/lib/stdlib/doc/src/erl_parse.xml b/lib/stdlib/doc/src/erl_parse.xml
index 739fde7a40..ae8a8afd5c 100644
--- a/lib/stdlib/doc/src/erl_parse.xml
+++ b/lib/stdlib/doc/src/erl_parse.xml
@@ -4,23 +4,21 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year>
-      <year>2007</year>
-      <holder>Ericsson AB, All Rights Reserved</holder>
+      <year>1996</year><year>2010</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
-  The contents of this file are subject to the Erlang Public License,
-  Version 1.1, (the "License"); you may not use this file except in
-  compliance with the License. You should have received a copy of the
-  Erlang Public License along with this software. If not, it can be
-  retrieved online at http://www.erlang.org/.
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
 
-  Software distributed under the License is distributed on an "AS IS"
-  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
-  the License for the specific language governing rights and limitations
-  under the License.
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
 
-  The Initial Developer of the Original Code is Ericsson AB.
     </legalnotice>
 
     <title>erl_parse</title>
@@ -188,7 +186,7 @@
     <p>A string which describes the error is obtained with the following call:
       </p>
     <code type="none">
-apply(Module, format_error, ErrorDescriptor)    </code>
+    Module:format_error(ErrorDescriptor)    </code>
   </section>
 
   <section>
diff --git a/lib/stdlib/doc/src/file_sorter.xml b/lib/stdlib/doc/src/file_sorter.xml
index b3f4da294c..ccb32659a0 100644
--- a/lib/stdlib/doc/src/file_sorter.xml
+++ b/lib/stdlib/doc/src/file_sorter.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>2001</year><year>2009</year>
+      <year>2001</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,12 +13,12 @@
       compliance with the License. You should have received a copy of the
       Erlang Public License along with this software. If not, it can be
       retrieved online at http://www.erlang.org/.
-    
+
       Software distributed under the License is distributed on an "AS IS"
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-    
+
     </legalnotice>
 
     <title>file_sorter</title>
@@ -83,13 +83,15 @@
        An ordering function is antisymmetric, transitive and total.
        <c>Fun(A,&nbsp;B)</c> should return <c>true</c> if <c>A</c>
        comes before <c>B</c> in the ordering, <c>false</c> otherwise.
+       An example of a typical ordering function is less than or equal
+       to, <c>=&lt;/2</c>.
        Using an ordering function will slow down the sort
        considerably. The <c>keysort</c>, <c>keymerge</c> and
        <c>keycheck</c> functions do not accept ordering functions.
       </item>
       <item><c>{unique, bool()}</c>. When sorting or merging files,
-       only the first of a sequence of terms that compare equal is
-       output if this option is set to <c>true</c>. The default
+       only the first of a sequence of terms that compare equal (<c>==</c>)
+       is output if this option is set to <c>true</c>. The default
        value is <c>false</c> which implies that all terms that
        compare equal are output. When checking files for
        sortedness, a check that no pair of consecutive terms
@@ -301,7 +303,7 @@ Value = Term</pre>
       <desc>
         <p>Sorts tuples on files. The sort is performed on the
           element(s) mentioned in <c>KeyPos</c>. If two tuples
-          compare equal on one element, next element according to
+          compare equal (<c>==</c>) on one element, next element according to
           <c>KeyPos</c> is compared. The sort is stable.
           </p>
         <p><c>keysort(N, FileName)</c> is equivalent to
diff --git a/lib/stdlib/doc/src/gb_sets.xml b/lib/stdlib/doc/src/gb_sets.xml
index accec623b9..60d8bcbfa3 100644
--- a/lib/stdlib/doc/src/gb_sets.xml
+++ b/lib/stdlib/doc/src/gb_sets.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>2001</year><year>2009</year>
+      <year>2001</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,12 +13,12 @@
       compliance with the License. You should have received a copy of the
       Erlang Public License along with this software. If not, it can be
       retrieved online at http://www.erlang.org/.
-    
+
       Software distributed under the License is distributed on an "AS IS"
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-    
+
     </legalnotice>
 
     <title>gb_sets</title>
@@ -34,6 +34,8 @@
       General Balanced Trees. This can be much more efficient than
       using ordered lists, for larger sets, but depends on the
       application.</p>
+    <p>This module considers two elements as different if and only if
+      they do not compare equal (<c>==</c>).</p>
   </description>
 
   <section>
diff --git a/lib/stdlib/doc/src/gb_trees.xml b/lib/stdlib/doc/src/gb_trees.xml
index 2bf18138c0..94f40c28bd 100644
--- a/lib/stdlib/doc/src/gb_trees.xml
+++ b/lib/stdlib/doc/src/gb_trees.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>2001</year><year>2009</year>
+      <year>2001</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,12 +13,12 @@
       compliance with the License. You should have received a copy of the
       Erlang Public License along with this software. If not, it can be
       retrieved online at http://www.erlang.org/.
-    
+
       Software distributed under the License is distributed on an "AS IS"
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-    
+
     </legalnotice>
 
     <title>gb_trees</title>
@@ -34,6 +34,8 @@
       Balanced Trees. These have no storage overhead compared to
       unbalanced binary trees, and their performance is in general
       better than AVL trees.</p>
+    <p>This module considers two keys as different if and only if
+      they do not compare equal (<c>==</c>).</p>
   </description>
 
   <section>
diff --git a/lib/stdlib/doc/src/io.xml b/lib/stdlib/doc/src/io.xml
index 6f9d979c9a..efbb1fc078 100644
--- a/lib/stdlib/doc/src/io.xml
+++ b/lib/stdlib/doc/src/io.xml
@@ -1021,7 +1021,7 @@ Error: error 11</pre>
     <p>A string which describes the error is obtained with the following
       call:</p>
     <code type="none">
-apply(Module, format_error, ErrorDescriptor)</code>
+Module:format_error(ErrorDescriptor)</code>
   </section>
 </erlref>
 
diff --git a/lib/stdlib/doc/src/lists.xml b/lib/stdlib/doc/src/lists.xml
index 39fc05420d..855a7e0244 100644
--- a/lib/stdlib/doc/src/lists.xml
+++ b/lib/stdlib/doc/src/lists.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2009</year>
+      <year>1996</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,12 +13,12 @@
       compliance with the License. You should have received a copy of the
       Erlang Public License along with this software. If not, it can be
       retrieved online at http://www.erlang.org/.
-    
+
       Software distributed under the License is distributed on an "AS IS"
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-    
+
     </legalnotice>
 
     <title>lists</title>
@@ -30,15 +30,16 @@
   <module>lists</module>
   <modulesummary>List Processing Functions</modulesummary>
   <description>
-    <p>This module contains functions for list processing. The functions
-      are organized in two groups: those in the first group perform a
-      particular operation on one or more lists, whereas those in the
-      second group are higher-order functions, using a fun as argument
-      to perform an operation on one list.</p>
+    <p>This module contains functions for list processing.</p>
+
     <p>Unless otherwise stated, all functions assume that position
       numbering starts at 1. That is, the first element of a list is at
       position 1.</p>
 
+    <p>Two terms <c>T1</c> and <c>T2</c> compare equal if
+      <c>T1&nbsp;==&nbsp;T2</c> evaluates to <c>true</c>. They match
+      if <c>T1&nbsp;=:=&nbsp;T2</c> evaluates to <c>true</c>.</p>
+
     <p>Whenever an <marker
       id="ordering_function"></marker><em>ordering function</em>
       <c>F</c> is expected as argument, it is assumed that the
diff --git a/lib/stdlib/doc/src/proplists.xml b/lib/stdlib/doc/src/proplists.xml
index a218dcf1fe..9f1c5b24ad 100644
--- a/lib/stdlib/doc/src/proplists.xml
+++ b/lib/stdlib/doc/src/proplists.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>2002</year><year>2009</year>
+      <year>2002</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,12 +13,12 @@
       compliance with the License. You should have received a copy of the
       Erlang Public License along with this software. If not, it can be
       retrieved online at http://www.erlang.org/.
-    
+
       Software distributed under the License is distributed on an "AS IS"
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-    
+
     </legalnotice>
 
     <title>proplists</title>
@@ -44,6 +44,9 @@
       such as options passed to a function where a user may specify options
       overriding the default settings, object properties, annotations,
       etc.</p>
+    <p>Two keys are considered equal if they match (<c>=:=</c>). In other
+      words, numbers are compared literally rather than by value, so that,
+      for instance, <c>1</c> and <c>1.0</c> are different keys.</p>
   </description>
   <funcs>
     <func>
diff --git a/lib/stdlib/doc/src/sofs.xml b/lib/stdlib/doc/src/sofs.xml
index ac434ec5b7..8c8ae51262 100644
--- a/lib/stdlib/doc/src/sofs.xml
+++ b/lib/stdlib/doc/src/sofs.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>2001</year><year>2009</year>
+      <year>2001</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,12 +13,12 @@
       compliance with the License. You should have received a copy of the
       Erlang Public License along with this software. If not, it can be
       retrieved online at http://www.erlang.org/.
-    
+
       Software distributed under the License is distributed on an "AS IS"
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-    
+
     </legalnotice>
 
     <title>sofs</title>
@@ -311,7 +311,7 @@
       applying Fun to the type of the given set), and that Fun does
       nothing but selecting, duplicating or rearranging parts of the
       elements. Specifying a SetFun as an integer I is equivalent to
-      specifying <c>{external, fun(X)&nbsp;-> element(I,&nbsp;X)}</c>,
+      specifying <c>{external, fun(X)&nbsp;-> element(I,&nbsp;X)&nbsp;end}</c>,
       but is to be preferred since it makes it possible to handle this
       case even more efficiently. Examples of SetFuns:</p>
     <pre>
@@ -336,6 +336,7 @@ fun(S) -> sofs:partition(1, S) end
       <c>badarg</c>, <c>bad_function</c>, or <c>type_mismatch</c>
       message when given badly formed arguments or sets the types of
       which are not compatible.</p>
+    <p>When comparing external sets the operator <c>==/2</c> is used.</p>
     <p><em>Types</em></p>
     <pre>
 anyset() = -&nbsp;an unordered, ordered or atomic set&nbsp;-
@@ -1108,7 +1109,13 @@ type() = -&nbsp;a type&nbsp;- </pre>
       <desc>
         <p>Returns <c>true</c> if the AnySet1 and AnySet2 
 	  are <seealso marker="#equal">equal</seealso>, <c>false</c> 
-	  otherwise.</p>
+	  otherwise. This example shows that <c>==/2</c> is used when
+          comparing sets for equality:</p>
+        <pre>
+1> <input>S1 = sofs:set([1.0]),</input>
+<input>S2 = sofs:set([1]),</input>
+<input>sofs:is_equal(S1, S2).</input>
+true</pre>
       </desc>
     </func>
     <func>