overview.edoc

OTP是开放电信平台的简称

			-*- html -*-

	EDoc overview page


@author Richard Carlsson <[e-mail]>
@copyright 2003-2006 Richard Carlsson
@version {@version}
@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 The overview page}</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.


== The overview page ==

When documentation is generated for an entire application, an overview
page, or "front page", is generated. (The page you are now reading is an
overview page.) This should contain the high-level description or user
manual for the application, leaving the finer details to the
documentation for individual modules. By default, the overview page is
generated from the file `overview.edoc' in the target directory
(typically, this is the `doc' subdirectory of the application
directory); see {@link edoc_doclet} for details.

The format of the overview file is the same as for EDoc documentation
comments (see {@section Introduction}), except that the lines do not
have leading '`%'' characters. Furthermore, all lines before the first
tag line are ignored, and can be used as a comment. All tags in the
overview file, such as `@@doc', `@@version', etc., refer to the
application as a whole; see {@section Overview tags} for details.

Here is an example of the contents of an overview file:
```** this is the overview.doc file for the application 'frob' **

   @@author R. J. Hacker <[e-mail]>
   @@copyright 2007 R. J. Hacker
   @@version 1.0.0
   @@title Welcome to the `frob' application!
   @@doc `frob' is a highly advanced frobnicator with low latency,
   ...
'''


== 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-docfile">`@docfile'</a></dt>
      <dd>Reads a plain documentation file (on the same format as an
      overview file - see {@section The overview page} for details), and
      uses the tags in that file as if they had been written in place of
      the `@docfile' tag. The content is the name of the file to be
      read; leading and trailing whitespace is ignored. See also <a
      href="#gtag-headerfile">`@headerfile'</a>.</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-headerfile">`@headerfile'</a></dt>
      <dd>Similar to the <a href="#gtag-docfile">`@docfile' tag</a>, but
      reads a file containing Erlang source code - generally this should
      be a header file (with the extension `.hrl'). If the file turns
      out to contain one or more function definitions or a module
      declaration, all tags that occur above the last such definition or
      module declaration are ignored, and EDoc will print a
      warning. This tag allows you to write documentation in a header
      file and insert it at a specific place in the documentation, even
      if the header file is used (i.e., included) by several
      modules. The `includes' option can be used to specify a search
      path (see {@link edoc:read_source/2}).</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>.'''
      These tags can also be written as "`TODO:'", e.g.:
```%% TODO: call your mother'''
      see {@section Wiki notation} for more information. 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} 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 be used in an overview file.
<dl>
  <dt><a name="otag-author">`@author'</a></dt>
      <dd>See the <a href="#mtag-author">`@author' module tag</a> for
      details.</dd>

  <dt><a name="otag-copyright">`@copyright'</a></dt>
      <dd>See the <a href="#mtag-copyright">`@copyright' module tag</a>
      for details.</dd>

  <dt><a name="otag-doc">`@doc'</a></dt>
      <dd>See the <a href="#mtag-doc">`@doc' module tag</a> for
      details.</dd>

  <dt><a name="otag-reference">`@reference'</a></dt>
      <dd>See the <a href="#mtag-reference">`@reference' module tag</a>
      for details.</dd>

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

  <dt><a name="otag-since">`@since'</a></dt>
      <dd>See the <a href="#mtag-since">`@since' module tag</a> for
      details.</dd>

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

  <dt><a name="otag-version">`@version'</a></dt>
      <dd>See the <a href="#mtag-version">`@version' module
      tag</a> for details.</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> 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>
      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>