overview.edoc

OTP是开放电信平台的简称

  <dt><a name="predefmacro-module"><code>@{@module}</code></a></dt>
      <dd>Expands to the name of the current module. Only defined when a
      module is being processed.</dd>

  <dt><a name="predefmacro-package"><code>@{@package}</code></a></dt>
      <dd>Expands to the name of the current package.</dd>

  <dt><a name="predefmacro-section"><code>@{@section
        <em>heading</em>}</code></a></dt>
      <dd>Expands to a hypertext link to the specified section heading;
      see {@section Headings} for more information.</dd>

  <dt><a name="predefmacro-type"><code>@{@type
      <em>type-expression</em>}</code></a></dt>
      <dd>Formats a type expression within `<code>...</code>'
      markup and with hypertext links for data types. For example,
      <code>@{@type {options, List::edoc:option_list()@@}}</code>
      generates "{@type {options, List::edoc:option_list()@}}". (Cf.
      {@section Escape sequences} below.)</dd>

  <dt><a name="predefmacro-time"><code>@{@time}</code></a></dt>
      <dd>Expands to the current time, as "<tt>Hr:Min:Sec</tt>",
      e.g. "{@time}".</dd>
</dl>

 === Escape sequences ===

To prevent certain characters from being interpreted as delimiters,
for example to produce the text "<code>@{@</code>" in the output, or use a
'`}'' character in the argument text of a macro call, the
following escape sequences may be used: <dl>
  <dt><code>@@{</code></dt>
      <dd>Expands to "`{'". Example:
```
   %% @doc A macro call starts with the sequence "@@@{@".'''
      </dd>
  <dt><code>@@}</code></dt>
      <dd>Expands to "`}'". Example:
```
   %% @doc ...@{@foo ...{Key, Value@@}...}...'''
      </dd>
  <dt><code>@@@@</code></dt>
      <dd>Expands to "`@'". Example:
```
   %% @doc Contact us at support@@@@@{@hostname}'''
      Will generate the text "Contact us at [e-mail]"
      if the macro `hostname' is bound to
      "`vaporware.acme.com'". Also:
```
   %% @doc You might want to write something like
   %% @@@@foo that will expand to @@foo and does not start
   %% a new tag even if it appears first in a line.'''
      </dd>
</dl>


== Type specifications ==

 === Function specifications ===

The following grammar describes the form of the specifications  
following a `@spec' tag:

<table summary="specification syntax grammar">
  <tr>
    <td><code>Spec</code></td>
    <td>::=</td>
    <td><code>FunType Def*
	  <br/>| FunctionName FunType Def*</code></td>
  </tr>
  <tr>
    <td><code>FunctionName</code></td>
    <td>::=</td>
    <td><code>Atom</code></td>
  </tr>
  <tr>
    <td><code>FunType</code></td>
    <td>::=</td>
    <td><code>"(" UnionTypes? ")" "->" UnionType</code></td>
  </tr>
  <tr>
    <td><code>UnionTypes</code></td>
    <td>::=</td>
    <td><code>UnionType
	  <br/>| UnionType "," UnionTypes</code></td>
  </tr>
  <tr>
    <td><code>UnionType</code></td>
    <td>::=</td>
    <td><code>UnionList
	  <br/>| Name "::" UnionList</code></td>
  </tr>
  <tr>
    <td><code>Name</code></td>
    <td>::=</td>
    <td><code>Variable</code></td>
  </tr>
  <tr>
    <td><code>UnionList</code></td>
    <td>::=</td>
    <td><code>Type
	  <br/>| Type "+" UnionList
	  <br/>| Type "|" UnionList</code></td>
  </tr>
  <tr>
    <td><code>Type</code></td>
    <td>::=</td>
    <td><code>TypeVariable
	  <br/>| Atom
	  <br/>| Integer
	  <br/>| Float
	  <br/>| FunType
	  <br/>| "{" UnionTypes? "}"
	  <br/>| "[" "]"
	  <br/>| "[" UnionType "]"
	  <br/>| TypeName "(" UnionTypes? ")"
	  <br/>| ModuleName ":" TypeName "(" UnionTypes? ")"
	  <br/>| "//" AppName "/" ModuleName ":" TypeName "(" UnionTypes? ")"</code></td>
  </tr>
  <tr>
    <td><code>TypeVariable</code></td>
    <td>::=</td>
    <td><code>Variable</code></td>
  </tr>
  <tr>
    <td><code>TypeName</code></td>
    <td>::=</td>
    <td><code>Atom</code></td>
  </tr>
  <tr>
    <td><code>ModuleName</code></td>
    <td>::=</td>
    <td><code>Atom
          <br/>| ModuleName "." Atom</code></td>
  </tr>
  <tr>
    <td><code>AppName</code></td>
    <td>::=</td>
    <td><code>Atom</code></td>
  </tr>
  <tr>
    <td><code>Def</code></td>
    <td>::=</td>
    <td><code>TypeVariable "=" UnionType
	  <br/>| TypeName "(" TypeVariables? ")" "=" UnionType</code></td>
  </tr>
  <tr>
    <td><code>TypeVariables</code></td>
    <td>::=</td>
    <td><code>TypeVariable
	  <br/>| TypeVariable "," TypeVariables</code></td>
  </tr>
</table>


Examples:
```
    %% @spec my_function(X::integer()) -> integer()'''
```
    %% @spec (X::integer()) -> integer()'''
```
    %% @spec sqrt(float()) -> float()'''
```
    %% @spec pair(S, T) -> {S, T}'''
```
    %% @spec append(List, List) -> List
    %%           List = [term()]'''
```
    %% @spec append(A::List, B::List) -> List
    %%           List = [term()]'''
```
    %% @spec open(File::filename()) -> file_descriptor()
    %%           filename() = string() + atom()'''
```
    %% @spec close(graphics:window()) -> ok'''

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>
`S', `T' and `List' are used to
simplify the type specifications, and may be supplied with
definitions. It is also possible to give definitions for named types,
which means that the name is simply an alias. (Use the
`@type' tag to document abstract data types.) If a named type
is defined in another module, it can be referred to as
`Module:TypeName(...)'.

Both the '`|'' and the '`+'' character may be
used to separate alternatives in union types; there is no semantic
difference. Note that the notation `[Type]' means "proper
(nil-terminated) list whose elements all belong to `Type'";
For example, `[atom()|integer()]' means the same thing as
`[atom()+integer()]', i.e., a proper list of atoms and/or
integers.

If only a type variable is given for a parameter, as in
"`pair(S, T) -> ...'", the same variable name may implicitly
be used as the parameter name; there is no need to write
"`pair(S::S, T::T) -> ...'".

EDoc automatically extracts possible parameter names from the source
code, to be used if no parameter name is given in the specification (or
if the specification is missing altogether). If this fails, EDoc will
generate a dummy parameter name, such as `X1'. This way, EDoc
can often produce helpful documentation even for code that does not
contain any annotations at all.

 === Type definitions ===

The following grammar (see above for auxiliary definitions) describes
the form of the definitions that may follow a `@type' tag:

<table summary="type definition grammar">
  <tr>
    <td><code>Typedef</code></td>
    <td>::=</td>
    <td><code>TypeName "(" TypeVariables? ")" Def*
	  <br/>| TypeName "(" TypeVariables? ")" "=" UnionType Def*</code></td>
  </tr>
</table>

(For a truly abstract data type, no equivalence is specified.) The main
definition may be followed by additional local definitions. Examples:
```
    %% @type myList(X). A special kind of lists ...'''
```
    %% @type filename() = string(). Atoms not allowed!'''
```
    %% @type thing(A) = {thong, A}
    %%           A = term().
    %%   A kind of wrapper type thingy.'''


 === Pre-defined data types ===

The following data types are predefined by EDoc, and may not be
redefined:
```
    any()
    atom()
    binary()
    bool()
    char()
    cons()
    deep_string()
    float()
    function()
    integer()
    list()
    nil()
    none()
    number()
    pid()
    port()
    reference()
    string()
    term()
    tuple()
'''
Details:
<ul>
  <li>`any()' means "any Erlang data type".
      `term()' is simply an alias for `any()'.</li>
  <li>`atom()', `binary()',
      `float()', `function()',
      `integer()', `pid()', `port()'
      and `reference()' are primitive data types of
      the Erlang programming language.</li>
  <li>`bool()' is the subset of `atom()' consisting
      of the atoms `true' and `false'.</li>
  <li>`char()' is a subset of
      `integer()' representing character codes.</li>
  <li>`tuple()' is the set of all tuples `{...}'.</li>
  <li>`list(T)' is just an alias for `[T]'.</li>
  <li>`nil()' is an alias for the empty list `[]'.</li>
  <li>`cons(H,T)' is the list constructor. This is usually not
      used directly. It is possible to recursively define `list(T)
      := nil()+cons(T,list(T))'.</li>
  <li>`string()' is an alias for `[char()]'.</li>
  <li>`deep_string()' is recursively defined as
      `[char()+deep_string()]'.</li>
  <li>`none()' means "no data type". E.g., a function
      that never returns has type `(...) -> none()'</li>
</ul>


== Acknowledgements ==

Since the first version of EDoc, several people have come up with
suggestions (Luke Gorrie, Joe Armstrong, Erik Stenman, Sean Hinde, Ulf
Wiger, ...), and some have even submitted code to demonstrate their
ideas (Vlad Dumitrescu, Johan Blom, Vijay Hirani, ...). None of that
code was actually included in the Great Rewriting that followed the
initial public release (EDoc version 0.1), but most of the central
points were addressed in the new system, such as better modularization
and possibility to plug in different layout engines, and making EDoc
understand the application directory layout.

It is now getting too hard to keep track of all the people who have made
further suggestions or submitted bug reports, but your input is always
appreciated. Thank you.