Merge branch 'dev' into bmk/snmp/agent/multi_engine_id_for_traps/OTP-9119

4 files changed, 154 insertions, 8 deletions

diff --git a/lib/edoc/doc/overview.edoc b/lib/edoc/doc/overview.edoc
index 9b25c17b1f..bd603b7a13 100644
--- a/lib/edoc/doc/overview.edoc
+++ b/lib/edoc/doc/overview.edoc
@@ -205,8 +205,12 @@ The following tags can be used anywhere within a module:
       the text. See {@section Type specifications} for syntax and
       examples.
       All data type descriptions are placed in a separate section of
-      the documentation, regardless of where the tags occur.</dd>
+      the documentation, regardless of where the tags occur.
 
+      Instead of specifying the complete type alias in an EDoc
+      documentation comment, type definitions from the actual
+      Erlang code can be re-used for documentation.
+      See {@section Type specifications} for examples.</dd>
 </dl>
 
 
@@ -405,7 +409,12 @@ The following tags can be used before a function definition:
       included in the specification, it must match the name in the
       actual code. When parameter names are not given in the
       specification, suitable names will be taken from the source
-      code if possible, and otherwise synthesized.</dd>
+      code if possible, and otherwise synthesized.
+
+      Instead of specifying the complete function type in an EDoc
+      documentation comment, specifications from the actual
+      Erlang code can be re-used for documentation.
+      See {@section Type specifications} for examples.</dd>
 
   <dt><a name="ftag-throws">`@throws'</a></dt>
       <dd>Specifies which types of terms may be thrown by the
@@ -763,6 +772,17 @@ following escape sequences may be used: <dl>
 
  === Function specifications ===
 
+<note>Although the syntax described in the following can still be used
+for specifying functions we recommend that Erlang specifications as
+described in <seealso marker="doc/reference_manual:typespec"> Types
+and Function Specification</seealso> should be added to the source
+code instead. This way the analyses of <seealso
+marker="dialyzer:dialyzer">Dialyzer</seealso>'s can be utilized in the
+process of keeping the documentation consistent and up-to-date.
+Erlang specifications will be used unless there is also a function
+specification (a `@spec' tag followed by a type) with the same name.
+</note>
+
 The following grammar describes the form of the specifications following
 a `@spec' tag. A '`?'' suffix implies that the element is optional.
 Function types have higher precedence than union types; e.g., "`(atom())
@@ -818,16 +838,51 @@ not as `(atom()) -> (atom() | integer())'.
 	  <br/>| Atom
 	  <br/>| Integer
 	  <br/>| Float
+          <br/>| Integer ".." Integer
 	  <br/>| FunType
+          <br/>| "fun(" FunType ")"
+          <br/>| "fun(...)"
 	  <br/>| "{" UnionTypes? "}"
+          <br/>| "#" Atom "{" Fields? "}"
 	  <br/>| "[" "]"
 	  <br/>| "[" UnionType "]"
+          <br/>| "[" UnionType "," "..." "]"
 	  <br/>| "(" UnionType ")"
+          <br/>| BinType
 	  <br/>| TypeName "(" UnionTypes? ")"
 	  <br/>| ModuleName ":" TypeName "(" UnionTypes? ")"
 	  <br/>| "//" AppName "/" ModuleName ":" TypeName "(" UnionTypes? ")"</code></td>
   </tr>
   <tr>
+    <td><code>Fields</code></td>
+    <td>::=</td>
+    <td><code>Field
+          <br/>| Fields "," Fields</code></td>
+  </tr>
+  <tr>
+    <td><code>Field</code></td>
+    <td>::=</td>
+    <td><code>Atom "=" UnionList</code></td>
+  </tr>
+  <tr>
+    <td><code>BinType</code></td>
+    <td>::=</td>
+    <td><code>"&lt;&lt;&gt;&gt;"
+          <br/>| "&lt;&lt;" BaseType "&gt;&gt;"
+          <br/>| "&lt;&lt;" UnitType "&gt;&gt;"
+          <br/>| "&lt;&lt;" BaseType "," UnitType "&gt;&gt;"</code></td>
+  </tr>
+  <tr>
+    <td><code>BaseType</code></td>
+    <td>::=</td>
+    <td><code>"_" ":" Integer</code></td>
+  </tr>
+  <tr>
+    <td><code>UnitType</code></td>
+    <td>::=</td>
+    <td><code>"_" ":" "_" "*" Integer</code></td>
+  </tr>
+  <tr>
     <td><code>TypeVariable</code></td>
     <td>::=</td>
     <td><code>Variable</code></td>
@@ -858,7 +913,7 @@ not as `(atom()) -> (atom() | integer())'.
   <tr>
     <td><code>Def</code></td>
     <td>::=</td>
-    <td><code>TypeVariable "=" UnionType
+    <td><code>TypeVariable "=" UnionList
 	  <br/>| TypeName "(" TypeVariables? ")" "=" UnionType</code></td>
   </tr>
   <tr>
@@ -873,6 +928,9 @@ not as `(atom()) -> (atom() | integer())'.
 
 Examples:
 ```
+    -spec my_function(X :: integer()) -> integer().
+    %% @doc Creates ...'''
+```
     %% @spec my_function(X::integer()) -> integer()'''
 ```
     %% @spec (X::integer()) -> integer()'''
@@ -895,6 +953,8 @@ Examples:
 ```
     %% @spec close(graphics:window()) -> ok'''
 
+The first example shows the recommended way of specifying functions.
+
 In the above examples, `X', `A', `B',
 and `File' are parameter names, used for referring to the
 parameters from the documentation text. The <em>type variables</em>
@@ -930,6 +990,13 @@ contain any annotations at all.
 
  === Type definitions ===
 
+<note>Although the syntax described in the following can still be used
+for specifying types we recommend that Erlang types as described in
+<seealso marker="doc/reference_manual:typespec"> Types and Function
+Specification</seealso> should be added to the source code instead.
+Erlang types will be used unless there is a type alias with the same
+name.</note>
+
 The following grammar (see above for auxiliary definitions) describes
 the form of the definitions that may follow a `@type' tag:
 
@@ -939,7 +1006,7 @@ the form of the definitions that may follow a `@type' tag:
     <td><code>Typedef</code></td>
     <td>::=</td>
     <td><code>TypeName "(" TypeVariables? ")" DefList?
-	  <br/>| TypeName "(" TypeVariables? ")" "=" UnionType DefList?</code></td>
+	  <br/>| TypeName "(" TypeVariables? ")" "=" UnionList DefList?</code></td>
   </tr>
 </tbody>
 </table>
@@ -947,6 +1014,11 @@ the form of the definitions that may follow a `@type' tag:
 (For a truly abstract data type, no equivalence is specified.) The main
 definition may be followed by additional local definitions. Examples:
 ```
+    -type my_list(X) :: [X]. %% A special kind of lists ...'''
+```
+    -opaque another_list(X) :: [X].
+    %% another_list() is a kind of list...'''
+```
     %% @type myList(X). A special kind of lists ...'''
 ```
     %% @type filename() = string(). Atoms not allowed!'''
@@ -955,6 +1027,7 @@ definition may be followed by additional local definitions. Examples:
     %%           A = term().
     %%   A kind of wrapper type thingy.'''
 
+The first two examples show the recommended way of specifying types.
 
  === Pre-defined data types ===
 
@@ -962,24 +1035,42 @@ The following data types are predefined by EDoc, and may not be
 redefined:
 ```
     any()
+    arity()
     atom()
     binary()
-    bool()
+    bitstring()
+    bool()        (allowed, but use boolean() instead)
+    boolean()
+    byte()
     char()
     cons()
     deep_string()
     float()
     function()
     integer()
+    iodata()
+    iolist()
     list()
+    maybe_improper_list()
+    mfa()
+    module()
     nil()
+    neg_integer()
+    node()
+    non_neg_integer()
+    nonempty_improper_list()
+    nonempty_list()
+    nonempty_maybe_improper_list()
+    nonempty_string()
     none()
     number()
     pid()
     port()
+    pos_integer()
     reference()
     string()
     term()
+    timeout()
     tuple()
 '''
 Details:
@@ -991,7 +1082,7 @@ Details:
       `integer()', `pid()', `port()'
       and `reference()' are primitive data types of
       the Erlang programming language.</li>
-  <li>`bool()' is the subset of `atom()' consisting
+  <li>`boolean()' is the subset of `atom()' consisting
       of the atoms `true' and `false'.</li>
   <li>`char()' is a subset of
       `integer()' representing character codes.</li>
diff --git a/lib/edoc/doc/src/Makefile b/lib/edoc/doc/src/Makefile
index 748691d173..5ee0096f0f 100644
--- a/lib/edoc/doc/src/Makefile
+++ b/lib/edoc/doc/src/Makefile
@@ -105,7 +105,7 @@ man: $(MAN3_FILES)
 $(XML_REF3_FILES):
 	escript $(DOCGEN)/priv/bin/xml_from_edoc.escript -def vsn $(EDOC_VSN) -i $(ERL_TOP)/lib/edoc/include $(SRC_DIR)/$(@:%.xml=%.erl)
 
-$(XML_CHAPTER_FILES):
+$(XML_CHAPTER_FILES): ../overview.edoc
 	escript $(DOCGEN)/priv/bin/xml_from_edoc.escript -def vsn $(EDOC_VSN) -chapter ../overview.edoc
 
 gifs: $(GIF_FILES:%=$(HTMLDIR)/%)
diff --git a/lib/edoc/doc/src/notes.xml b/lib/edoc/doc/src/notes.xml
index afcccf22b5..c18a126264 100644
--- a/lib/edoc/doc/src/notes.xml
+++ b/lib/edoc/doc/src/notes.xml
@@ -31,6 +31,61 @@
   <p>This document describes the changes made to the EDoc
     application.</p>
 
+<section><title>Edoc 0.7.7</title>
+
+    <section><title>Fixed Bugs and Malfunctions</title>
+      <list>
+        <item>
+	    <p> Add encoding when parsing Wiki text. EDoc used to
+	    fail on strings such as "���". (Thanks to Richard
+	    Carlsson.) </p>
+          <p>
+	    Own Id: OTP-9109</p>
+        </item>
+      </list>
+    </section>
+
+
+    <section><title>Improvements and New Features</title>
+      <list>
+        <item>
+	    <p> It is now possible to use Erlang specifications and
+	    types in EDoc documentation. Erlang specifications and
+	    types will be used unless there is also a function
+	    specification (<c>@spec</c>) or a type alias
+	    (<c>@type</c>) with the same name. In the current
+	    implementation the placement of <c>-spec</c> matters: it
+	    should be placed where the <c>@spec</c> would otherwise
+	    have been placed. </p>
+	    <p>Not all Erlang types are included in the
+	    documentation, but only those exported by some
+	    <c>export_type</c> declaration or used by some documented
+	    Erlang specification (<c>-spec</c>). </p>
+	    <p> There is currently no support for overloaded Erlang
+	    specifications. </p>
+	    <p> The syntax definitions of EDoc have been augmented to
+	    cope with most of the Erlang types. (But we recommend
+	    that Erlang types should be used instead.) </p>
+	    <p> <c>edoc:read_source()</c> takes one new option,
+	    <c>report_missing_types</c>. <c>edoc_layout:module()</c>
+	    takes one new option, <c>pretty_printer</c>. </p>
+          <p>
+	    Own Id: OTP-8525</p>
+        </item>
+        <item>
+	    <p> The <c>edoc_lib</c> module is meant to be private,
+	    but since it is referred to from other man pages it has
+	    been included in the OTP documentation. The modifications
+	    introduced in this ticket make all functions private
+	    except those referred to from other pages. </p>
+          <p>
+	    Own Id: OTP-9110</p>
+        </item>
+      </list>
+    </section>
+
+</section>
+
 <section><title>Edoc 0.7.6.8</title>
 
     <section><title>Improvements and New Features</title>
diff --git a/lib/edoc/doc/src/ref_man.xml b/lib/edoc/doc/src/ref_man.xml
index 619fbaa7ca..a9af8740b9 100644
--- a/lib/edoc/doc/src/ref_man.xml
+++ b/lib/edoc/doc/src/ref_man.xml
@@ -4,7 +4,7 @@
 <application xmlns:xi="http://www.w3.org/2001/XInclude">
   <header>
     <copyright>
-      <year>2006</year><year>2009</year>
+      <year>2006</year><year>2011</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>