overview.edoc

OTP是开放电信平台的简称

			-*- html -*-

	EDoc overview page


@author Richard Carlsson <[e-mail]>
@copyright 2003-2006 Richard Carlsson
@version {@vsn}
@title Welcome to EDoc

@doc EDoc is the Erlang program documentation generator. Inspired by the
Javadoc<sup><font size="-3">TM</font></sup> tool for the Java<sup><font
size="-3">TM</font></sup> programming language, EDoc is adapted to the
conventions of the Erlang world, and has several features not found in
Javadoc.

== Contents ==

<ol>
  <li>{@section Introduction}</li>
  <li>{@section Running EDoc}</li>
  <li>{@section Generic tags}</li>
  <li>{@section Overview tags}</li>
  <li>{@section Module tags}</li>
  <li>{@section Function tags}</li>
  <li>{@section References}</li>
  <li>{@section Notes on XHTML}</li>
  <li>{@section Wiki notation}</li>
  <li>{@section Macro expansion}</li>
  <li>{@section Type specifications}</li>
  <li>{@section Acknowledgements}</li>
</ol>

== Introduction ==

EDoc lets you write the documentation of an Erlang program as
comments in the source code itself, using <em>tags</em> on the form
"`@Name ...'". A source file does not have to contain tags
for EDoc to generate its documentation, but without tags the result will
only contain the basic available information that can be extracted from
the module.

A tag must be the first thing on a comment line, except for leading
'`%'' characters and whitespace. The comment must be between
program declarations, and not on the same line as any program text. All
the following text - including consecutive comment lines - up until the
end of the comment or the next tagged line, is taken as the
<em>content</em> of the tag.

Tags are associated with the nearest following program construct "of
significance" (the module name declaration and function
definitions). Other constructs are ignored; e.g., in:
```
   %% @doc Prints the value X.

   -record(foo, {x, y, z}).

   print(X) -> ...
'''
the `@doc' tag is associated with the function `print/1'.

Note that in a comment such as:
```% % @doc ...'''
the tag is ignored, because only the first '`%'' character is
considered "leading". This allows tags to be "commented out".

Some tags, such as `@type', do not need to be associated
with any program construct. These may be placed at the end of the file,
in the "footer".


== Running EDoc ==

The following are the main functions for running EDoc:
    <ul>
      <li>{@link edoc:application/2}: Creates documentation for a
	  typical Erlang application.</li>
      <li>{@link edoc:packages/2}: Creates documentation for one or
	  more packages, automatically locating source files.</li>
      <li>{@link edoc:files/2}: Creates documentation for a
	  specified set of source files.</li>
      <li>{@link edoc:run/3}: General interface function; the common
          back-end for the above functions. Options are documented here.</li>
    </ul>

Note that the function {@link edoc:file/2} belongs to the old, deprecated
interface (from EDoc version 0.1), and should not be used.


== Generic tags ==

The following tags can be used anywhere within a module:
<dl>
  <dt><a name="gtag-clear">`@clear'</a></dt>

      <dd>This tag causes all tags above it (up to the previous program
	construct), to be discarded, including the `@clear'
	tag itself. The text following the tag
	is also ignored. <em>This is typically only useful in code
	containing conditional compilation, when preprocessing is turned
	on.</em> (Preprocessing is turned off by default.) E.g., in
```-ifdef(DEBUG).
   %% @doc ...
   foo(...) -> ...
   -endif.
   %% @clear

   %% @doc ...
   bar(...) -> ...'''
        the `@clear' tag makes sure that EDoc does not see
	two `@doc' tags before the function `bar',
	even if the code for function `foo' is removed by
	preprocessing. (There is no way for EDoc to see what the first
	`@doc' tag "really" belongs to, since preprocessing
	strips away all such information.)</dd>

  <dt><a name="gtag-end">`@end'</a></dt>
      <dd>The text following this tag is always ignored. Use this to
      mark the end of the previous tag, when necessary, as e.g. in:
```%% ----------------------------------
   %% ...
   %% @doc ...
   %% ...
   %% @end
   %% ----------------------------------'''
      to avoid including the last "ruler" line in the
      `@doc' tag.

      <em>Note: using some other "dummy" `@'-tag for
      the same purpose might work in a particular implementation of
      EDoc, but is not guaranteed to.  Always use `@end'
      to ensure future compatibility.</em></dd>

  <dt><a name="gtag-todo">`@todo' (or `@TODO')</a></dt>
      <dd>Attaches a To-Do note to a function, module, package, or
      overview-page. The content can be any XHTML text describing
      the issue, e.g.:
```%% @TODO Finish writing the documentation.'''
      or
```%% @todo Implement <a href="http://www.ietf.org/rfc/rfc2549.txt">RFC 2549</a>.'''
      To-Do notes are normally not shown unless the `todo' option is
      turned on (see {@link edoc:get_doc/2}).</dd>

  <dt><a name="gtag-type">`@type'</a></dt>
      <dd>Documents an abstract data type or type alias. The content
      consists of a type declaration or definition, optionally
      followed by a period ('`.'') separator and XHTML
      text describing the type (i.e., its purpose, use, etc.). There
      must be at least one whitespace character between the
      '`.'' and the text. See {@section Type specifications} below
      for syntax and examples.
      All data type descriptions are placed in a separate section of
      the documentation, regardless of where the tags occur.</dd>

</dl>



== Overview tags ==

The following tags can only be used in an overview file:
<dl>
  <dt><a name="otag-title">`@title'</a></dt>
      <dd>Specifies a title for the overview page. The content
      can be arbitrary text.</dd>
</dl>


== Module tags ==

The following tags can be used before a module declaration:
<dl>
  <dt><a name="mtag-author">`@author'</a></dt>
      <dd>Specifies the name of an author, along with contact
      information. An e-mail address can be given within `<...>'
      delimiters, and a URI within `[...]' delimiters. Both e-mail and
      URI are optional, and any surrounding whitespace is stripped from
      all strings.

      The name is the first nonempty string that is not within `<...>'
      or `[...]', and does not contain only whitespace. (In other words,
      the name can come before, between, or after the e-mail and URI,
      but cannot be split up; any sections after the first are ignored.)
      If an e-mail address is given, but no name, the e-mail string will
      be used also for the name. If no `<...>' section is present, but
      the name string contains an '`@'' character, it is assumed to be
      an e-mail address. Not both name and e-mail may be left out.

      Examples:
```%% @author Richard Carlsson'''

```%% @author Richard Carlsson <[e-mail]>
   %%   [http://user.it.uu.se/~richardc/]'''

```%% @author <[e-mail]>'''

```%% @author [e-mail] [http://user.it.uu.se/~richardc/]'''
      </dd>

<dt><a name="mtag-copyright">`@copyright'</a></dt>
      <dd>Specifies the module copyrights. The content can be
      arbitrary text; for example:
```
   %% @copyright 2001-2003 Richard Carlsson'''
      </dd>

  <dt><a name="mtag-deprecated">`@deprecated'</a></dt>
      <dd>Mark the module as deprecated, indicating that it should no
      longer be used. The content must be well-formed XHTML, and should
      preferably include a `@{@link}' reference to a
      replacement; as in:
```
   %% @deprecated Please use the module @{@link foo} instead.'''
      </dd>

  <dt><a name="mtag-doc">`@doc'</a></dt>
      <dd>Describes the module, using well-formed XHTML text. The
      first sentence is used as a summary (see the
      <a href="#ftag-doc">`@doc' function tag</a> below
      for details). For example.:
```%% @doc This is a <em>very</em> useful module. It is ...'''</dd>

  <dt><a name="mtag-hidden">`@hidden'</a></dt>
      <dd>Marks the module so that it will not appear in the
      documentation (even if "private" documentation is generated).
      Useful for sample code, test modules, etc. The content can be
      used as a comment; it is ignored by EDoc.</dd>

  <dt><a name="mtag-private">`@private'</a></dt>
      <dd>Marks the module as private (i.e., not part of the public
      interface), so that it will not appear in the normal
      documentation. (If "private" documentation is generated, the
      module will be included.) The content can be used as a comment; it
      is ignored by EDoc.</dd>

  <dt><a name="mtag-reference">`@reference'</a></dt>
      <dd>Specifies a reference to some arbitrary external resource,
      such as an article, book, or web site. The content must be
      well-formed XHTML text. Examples:
```%% @reference Pratchett, T., <em>Interesting Times</em>,
   %% Victor Gollancz Ltd, 1994.'''

```%% @reference See <a href="www.google.com">Google</a> for
   %% more information.'''
      </dd>

  <dt><a name="mtag-see">`@see'</a></dt>
      <dd>See the <a href="#ftag-see">`@see' function tag</a>
      below for details.</dd>

  <dt><a name="mtag-since">`@since'</a></dt>
      <dd>Specifies when the module was introduced, with respect to
      the application, package, release or distribution it is part
      of. The content can be arbitrary text.</dd>

  <dt><a name="mtag-version">`@version'</a></dt>
      <dd>Specifies the module version. The content can be arbitrary
      text.</dd>

</dl>



== Function tags ==

The following tags can be used before a function definition:
<dl>
  <dt><a name="ftag-deprecated">`@deprecated'</a></dt>
      <dd>See the <a href="#mtag-deprecated">`@deprecated'
      module tag</a> for details.</dd>

  <dt><a name="ftag-doc">`@doc'</a></dt>
      <dd>XHTML text describing the function. The first
      sentence of the text is used as a quick summary; this ends at
      the first period character ('`.'') or exclamation mark
      ('`!'') that is followed by a whitespace character, a
      line break, or the end of the tag text, and is not within XML
      markup. (As an exception, the first sentence may be within an
      initial paragraph element)</dd>

  <dt><a name="ftag-equiv">`@equiv'</a></dt>
      <dd>Specify equivalence to another function call/expression.
      The content must be a proper Erlang expression. If the
      expression is a function call, a cross-reference to the called
      function is created automatically. Typically, this tag is used
      instead of `@doc'. </dd>

  <dt><a name="ftag-hidden">`@hidden'</a></dt>
      <dd>Marks the function so that it will not appear in the
      documentation (even if "private" documentation is generated).
      Useful for debug/test functions, etc. The content can be
      used as a comment; it is ignored by EDoc.</dd>

  <dt><a name="ftag-private">`@private'</a></dt>
      <dd>Marks the function as private (i.e., not part of the public
      interface), so that it will not appear in the normal
      documentation. (If "private" documentation is generated, the
      function will be included.) Only useful for exported functions,
      e.g. entry points for `spawn'. (Non-exported functions are
      always "private".) The content can be used as a comment; it is
      ignored by EDoc.</dd>

  <dt><a name="ftag-see">`@see'</a></dt>
      <dd>Make a reference to a module, function, datatype, or