overview.edoc

OTP是开放电信平台的简称

      application. (See {@section References} below.)
      The content consists of a reference, optionally followed by a
      period ('`.''), one or more whitespace characters, and
      XHTML text to be used for the label; for example "`@see edoc'" or
      "`@see edoc. <b>EDoc</b>'". If no label text is specified, the
      reference itself is used as the label.</dd>

  <dt><a name="ftag-since">`@since'</a></dt>
      <dd>Specifies in what version of the module the function was
      introduced; cf. the
      <a href="#mtag-version">`@version'
      module tag</a>. The content can be arbitrary text.</dd>

  <dt><a name="ftag-spec">`@spec'</a></dt>
      <dd>Used to specify the function type; see {@section Type
      specifications} below for syntax. If the function name is
      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>

  <dt><a name="ftag-throws">`@throws'</a></dt>
      <dd>Specifies which types of terms may be thrown by the
      function, if its execution terminates abruptly due to a call to
      `erlang:throw(Term)'. The content is a type expression (see {@section
      Type specifications}), and can be a union type.

      Note that exceptions of type `exit' (as caused by calls to
      `erlang:exit(Term)') and `error' (run-time errors such as `badarg'
      or `badarith') are not viewed as part of the normal interface of
      the function, and cannot be documented with the `@throws' tag.</dd>

  <dt><a name="ftag-type">`@type'</a></dt>
      <dd>See the <a href="#gtag-type">`@type' generic tag</a>
      for details. Placing a `@type' tag by a function
      definition may be convenient, but does not affect where the
      description is placed in the generated documentation.</dd>
</dl>



== References ==

In several contexts (`@see' tags, `@link' macros, etc.), EDoc lets
you refer to the generated documentation for modules, functions,
datatypes, and applications, using a simple and compact syntax. The
possible formats for references are:
<table border="1" summary="reference syntax">
  <tr><th>Reference syntax</th><th>Example</th><th>Scope</th></tr>
  <tr><td>`Module'</td><td>{@link edoc_run}, `erl.lang.list'</td><td>Global</td></tr>
  <tr><td>`Package.*'</td><td>`erl.lang.*'</td><td>Global</td></tr>
  <tr><td>`Function/Arity'</td><td>`file/2'</td><td>Within module</td></tr>
  <tr><td>`Module:Function/Arity'</td><td>{@link edoc:application/2}</td><td>Global</td></tr>
  <tr><td>`Type()'</td><td>`filename()'</td><td>Within module</td></tr>
  <tr><td>`Module:Type()'</td><td>{@link edoc:edoc_module()}</td><td>Global</td></tr>
  <tr><td>`//Application'</td><td>{@link //edoc}</td><td>Global</td></tr>
  <tr><td>`//Application/Module'</td><td>{@link //edoc/edoc_doclet}</td><td>Global</td></tr>
  <tr><td>`//Application/Module:Function/Arity'</td><td>{@link //edoc/edoc_run:file/1}</td><td>Global</td></tr>
  <tr><td>`//Application/Module:Type()'</td><td>{@link //edoc/edoc:edoc_module()}</td><td>Global</td></tr>
</table>


EDoc will resolve references using the information it finds in
`edoc-info'-files at the locations specified with the `doc_path'
option. EDoc will automatically (and somewhat intelligently) try to find
any local `edoc-info'-files using the current code path, and add them to
the end of the `doc_path' list. The target doc-directory is also
searched for an existing info file; this allows documentation to be
built incrementally. (Use the `new' option to ignore any old info
file.)

Note that if the name of a module, function or datatype is explicitly
qualified with an application (as in "`//edoc/edoc_run'"), this
overrides any other information about that name, and the reference will
be made relative to the location of the application (if it can be
found). This makes it possible to refer to e.g. a module "`fred'" as
"`//foo/fred'" without accidentally getting a reference to
"`//bar/fred'". You should not use this form of explicit references for
names that are local to the application you are currently creating -
they will always be resolved correctly.

Note that module-local references such as `file/2' only work properly
within a module. In an overview-page like this (i.e., the one you are
currently reading), no module context is available.

== Notes on XHTML ==

In several places, XHTML markup can be used in the documentation
text, in particular in `@doc' tags. The main differences from
HTML are the following:
<ul>
  <li>All elements must have explicit start and end tags, and be
      correctly nested. This means that you cannot e.g. write a
      `<li>' tag without also writing a corresponding `</li>'
      tag in the right place. This could be an annoyance
      at times, but has the great advantage that EDoc can report all
      malformed XHTML in your source code, rather than propagate the
      errors to the generated documentation.</li>
  <li>XHTML tag and attribute names should always be lower-case.</li>
  <li>Attributes must be quoted, as in e.g. `<a
      name="top">'.</li>
</ul>
To write an element like the HTML `<br>', which has no actual content,
you can write either the full `<br></br>', or better, use the XHTML
abbreviated form `<br/>'.

Since the purpose of EDoc is to document programs, there is also a
limited form of "wiki"-syntax available for making program code easier
to write inline (and to make the doc-comments easier to read).
See {@section Wiki notation} below for details.

The HTML heading tags `h1' and `h2' are reserved for use by EDoc.
Headings in documentation source code should start at `h3'. There is
however a special syntax for writing headings which avoids using
specific level numbers altogether; see {@section Headings} below for details.

EDoc uses {@link //xmerl. XMerL} to parse and export XML markup.


== Wiki notation ==

When EDoc parses XHTML, it does additional pre- and post-processing of
the text in order to expand certain notation specific to EDoc into
proper XHTML markup. This "wiki" ([http://en.wikipedia.org/wiki/Wiki])
notation is intended to make it easier to write source code
documentation.

 === Empty lines separate paragraphs ===

Leaving an empty line in XHTML text (i.e., a line which except for
any leading start-of-comment '<tt>%</tt>' characters contains only
whitespace), will make EDoc split the text before and
after the empty line into separate paragraphs. For example:
```%% @doc This will all be part of the first paragraph.
   %% It can stretch over several lines and contain <em>any
   %% XHTML markup</em>.
   %% 
   %% This is the second paragraph. The above line is
   %% regarded as "empty" by EDoc, even though it ends with
   %% a space.'''
will generate the following text:
<blockquote><p>This will all be part of the first paragraph. It can
stretch over several lines and contain <em>any XHTML markup</em>.</p>
This is the second paragraph. The above line is regarded as "empty" by
EDoc, even though it ends with a space.</blockquote>

Paragraph splitting takes place after the actual XHTML parsing. It only
affects block-level text, and not e.g., text within `<pre>' markup, or
text that is already within `<p>' markup.

 === Headings ===

Section headings, sub-headings, and sub-sub-headings, can be written
using the following notation:
```== Heading ==
   === Sub-heading ===
   ==== Sub-sub-heading ===='''
Such a heading must be alone on a line, except for whitespace, and
cannot be split over several lines. A link target is automatically
created for the heading, by replacing any whitespace within the text by
a single underscore character. E.g.,
```== Concerning Hobbits =='''
is equivalent to
```<h3><a name="Concerning_Hobbits">Concerning Hobbits</a></h3>'''
Thus, headings using this notation should not contain characters that
may not be part of URL labels, except for whitespace. If you need to
create such headings, you have to use the explicit XHTML markup.

A hypertext link to a heading written this way can be created using the
`@section' macro, which transforms the argument text into a label as
described above. E.g.,
```@{@section Concerning Hobbits}'''
is eqivalent to writing
```<a href="#Concerning_Hobbits">Concerning Hobbits</a>'''

The above expansions take place before XML parsing.

 === External links ===

Writing a URL within brackets, as in "`[http://www.w3c.org/]'", will
generate a hyperlink such as [http://www.w3c.org/], using the URL both
for the destination and the label of the reference, equivalent to writing
"`<a href="http://www.w3c.org/"><tt>http://www.w3c.org/</tt></a>'". This
short-hand keeps external URL references short and readable. The
recognized protocols are `http', `ftp', and `file'. This expansion takes
place before XML parsing.

 === Verbatim quoting ===

In XHTML text, the '<code>&#x60;</code>' character (Unicode `000060',
known as "grave accent" or "back-quote") can be used for verbatim
quoting. This expansion takes place before XML parsing.

<ul>
  <li>A character sequence "<code>&#x60;...'</code>" or
      "<code>&#x60;&#x60;...''</code>" will be expanded to
      "`<code>...</code>'", where all occurrences of the special XML
      characters '`<'' and '`&'' (and for completeness, also '`>'') in
      the quoted text have been escaped to "`&lt;'", "`&amp;'", and
      "`&gt;'", respectively.
      All whitespace is stripped from the beginning and end of the
      quoted text.

      Double back-quotes "<code>&#x60;&#x60;...''</code>" can be used
      to quote text containing single '`` ' ''' characters. The automatic
      stripping of any surrounding whitespace makes it possible to write
      things like "<code>&#x60;&#x60; 'foo@bar' ''</code>".

      To quote text containing "<code>''</code>" verbatim,
      explicit `<code>' markup or similar must be used.</li>

  <li>A character sequence "<code>&#x60;&#x60;&#x60;...'''</code>"
      will be expanded to "`<pre><![CDATA[...]]></pre>'", which disables
      all XML markup within the quoted text, and displays the result in
      fixed-font with preserved indentation. Whitespace is stripped from
      the end of the quoted text, but not from the beginning, except for
      whole leading lines of whitespace. This is
      useful for multi-line code examples, or displayed
      one-liners.</li>

  <li>To produce a single '<code>&#x60;</code>'-character in XML
      without beginning a new quote, you can write "<code>&#x60;'</code>"
      (no space between the '<code>&#x60;</code>' and the '<code>'</code>').
      You can of course also use the XML character entity
      "`&#x60;'".</li>
</ul>

Examples:
  ```%% @doc ...where the variable `Foo' refers to... '''

  ```%% @doc ...returns the atom `` '[e-mail]' ''... '''

  <pre>
     %% @doc ...use the command &#x60;&#x60;&#x60;erl -name foo''' to...</pre>

  <pre>
     %% @doc ...as in the following code:
     %% &#x60;&#x60;&#x60;f(X) ->
     %%       case X of
     %%          ...
     %%       end'''</pre>

  <pre>
     %% @doc ...or in the following:
     %% &#x60;&#x60;&#x60;
     %%     g(X) ->
     %%       fun () -> ... end
     %% '''</pre>


== Macro expansion ==

Before the content of a tag is parsed, the text undergoes <em>macro
expansion</em>. The syntax for macro calls is:
<pre>
    @{@<em>name</em>}</pre>
or
<pre>
    @{@<em>name</em> <em>argument</em>}</pre>
where <em>name</em> and <em>argument</em> are separated by one or more
whitespace characters. The argument can be any text, which may contain
other macro calls. The number of non-escaped "<code>@{@</code>" and
"`}'" delimiters must be balanced.

 The argument text is first expanded in the current environment, and
the result is bound to the <em>macro parameter</em>, written
<code>@{@?}</code>. (If no argument is given, <code>@{@?}</code> is
bound to the empty string.)  The macro definition is then substituted
for the call, and expansion continues over the resulting text. Recursive
macro expansions are not allowed.

 === User-defined macros ===

Users can define their own macros by using the `def' EDoc
option; see {@link edoc:file/2} and {@link edoc:get_doc/2} for more
information.

 === Predefined macros ===

<dl>
  <dt><a name="predefmacro-date"><code>@{@date}</code></a></dt>
      <dd>Expands to the current date, as "<tt>Month Day Year</tt>",
      e.g. "{@date}".</dd>

  <dt><a name="predefmacro-docRoot"><code>@{@docRoot}</code></a></dt>
      <dd>Expands to the relative URL path (such as
      `"../../.."') from the current page to the root
      directory of the generated documentation. This can be used to
      create XHTML references such as `<img
      src="@{@docRoot}/images/logo.jpeg">' that are independent of how
      deep down in a package structure they occur. If packages are not
      used (i.e., if all modules are in the "empty" package),
      <code>@{@docRoot}</code> will always resolve to the empty
      string.</dd>

  <dt><a name="predefmacro-link"><code>@{@link <em>reference</em>.
		    <em>description</em>}</code></a></dt>
      <dd>This creates a hypertext link; cf. the
      <a href="#ftag-see">`@see' function tag</a> above for
      details. The description text (including the period separator)
      is optional; if no text is given, the reference itself is
      used. For example, <code>@{@link edoc:file/2}</code> creates the
      link {@link edoc:file/2}, and `@{@link edoc:file/2. <em>this link</em>}'
      creates {@link edoc:file/2. <em>this link</em>}.</dd>