aboutsummaryrefslogtreecommitdiffstats
path: root/lib/edoc/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/edoc/doc')
-rw-r--r--lib/edoc/doc/overview.edoc103
-rw-r--r--lib/edoc/doc/src/Makefile2
-rw-r--r--lib/edoc/doc/src/notes.xml57
-rw-r--r--lib/edoc/doc/src/ref_man.xml2
4 files changed, 155 insertions, 9 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..630271b115 100644
--- a/lib/edoc/doc/src/notes.xml
+++ b/lib/edoc/doc/src/notes.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>2007</year><year>2010</year>
+ <year>2007</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -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>