<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- Welcome to EDoc
</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/edoc-0.7.10.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>EDoc</strong><br><strong>User's Guide</strong><br><small>Version 0.7.10</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu"><li id="loadscrollpos" title="Welcome to EDoc
" expanded="true">Welcome to EDoc
<ul>
<li><a href="chapter.html">
Top of chapter
</a></li>
<li title="Contents"><a href="chapter.html#id58004">Contents</a></li>
<li title="Introduction"><a href="chapter.html#id64857">Introduction</a></li>
<li title="Running EDoc"><a href="chapter.html#id57511">Running EDoc</a></li>
<li title="The overview page"><a href="chapter.html#id61696">The overview page</a></li>
<li title="Generic tags"><a href="chapter.html#id61191">Generic tags</a></li>
<li title="Overview tags"><a href="chapter.html#id61227">Overview tags</a></li>
<li title="Module tags"><a href="chapter.html#id61330">Module tags</a></li>
<li title="Function tags"><a href="chapter.html#id63302">Function tags</a></li>
<li title="References"><a href="chapter.html#id64690">References</a></li>
<li title="Notes on XHTML"><a href="chapter.html#id60973">Notes on XHTML</a></li>
<li title="Wiki notation"><a href="chapter.html#id61084">Wiki notation</a></li>
<li title="Macro expansion"><a href="chapter.html#id58238">Macro expansion</a></li>
<li title="Type specifications"><a href="chapter.html#id63489">Type specifications</a></li>
<li title="Acknowledgements"><a href="chapter.html#id64274">Acknowledgements</a></li>
</ul>
</li></ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>1 Welcome to EDoc
</h1>
<p>EDoc is the Erlang program documentation generator. Inspired by the
Javadoc(TM) tool for the Java(TM) programming language, EDoc is adapted to the
conventions of the Erlang world, and has several features not found in
Javadoc.</p>
<h3><a name="id58004">1.1
Contents</a></h3>
<a name="Contents"></a>
<ul>
<li><span class="bold_code"><a href="#Introduction">Introduction</a></span></li>
<li><span class="bold_code"><a href="#Running_EDoc">Running EDoc</a></span></li>
<li><span class="bold_code"><a href="#The_overview_page">The overview page</a></span></li>
<li><span class="bold_code"><a href="#Generic_tags">Generic tags</a></span></li>
<li><span class="bold_code"><a href="#Overview_tags">Overview tags</a></span></li>
<li><span class="bold_code"><a href="#Module_tags">Module tags</a></span></li>
<li><span class="bold_code"><a href="#Function_tags">Function tags</a></span></li>
<li><span class="bold_code"><a href="#References">References</a></span></li>
<li><span class="bold_code"><a href="#Notes_on_XHTML">Notes on XHTML</a></span></li>
<li><span class="bold_code"><a href="#Wiki_notation">Wiki notation</a></span></li>
<li><span class="bold_code"><a href="#Macro_expansion">Macro expansion</a></span></li>
<li><span class="bold_code"><a href="#Type_specifications">Type specifications</a></span></li>
<li><span class="bold_code"><a href="#Acknowledgements">Acknowledgements</a></span></li>
</ul>
<h3><a name="id64857">1.2
Introduction</a></h3>
<a name="Introduction"></a>
<p>EDoc lets you write the documentation of an Erlang program as
comments in the source code itself, using <strong>tags</strong> on the form
"<span class="code">@Name ...</span>". 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.</p>
<p>A tag must be the first thing on a comment line, except for leading
'<span class="code">%</span>' 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
<strong>content</strong> of the tag.</p>
<p>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:
</p>
<div class="example"><pre> %% @doc Prints the value X.
-record(foo, {x, y, z}).
print(X) -> ...</pre></div>
<p>
the <span class="code">@doc</span> tag is associated with the function <span class="code">print/1</span>.</p>
<p>Note that in a comment such as:
</p>
<div class="example"><pre> % % @doc ...</pre></div>
<p>
the tag is ignored, because only the first '<span class="code">%</span>' character is
considered "leading". This allows tags to be "commented out".</p>
<p>Some tags, such as <span class="code">@type</span>, do not need to be associated
with any program construct. These may be placed at the end of the file,
in the "footer".</p>
<h3><a name="id57511">1.3
Running EDoc</a></h3>
<a name="Running_EDoc"></a>
<p>
The following are the main functions for running EDoc:
</p>
<ul>
<li><p><span class="bold_code"><a href="edoc.html#application-2">edoc:application/2</a></span>: Creates documentation for a
typical Erlang application.</p></li>
<li><p><span class="bold_code"><a href="edoc.html#packages-2">edoc:packages/2</a></span>: Creates documentation for one or
more packages, automatically locating source files.</p></li>
<li><p><span class="bold_code"><a href="edoc.html#files-2">edoc:files/2</a></span>: Creates documentation for a
specified set of source files.</p></li>
<li><p><span class="bold_code"><a href="edoc.html#run-3">edoc:run/3</a></span>: General interface function; the common
back-end for the above functions. Options are documented here.</p></li>
</ul>
<p>Note that the function <span class="bold_code"><a href="edoc.html#file-2">edoc:file/2</a></span> belongs to the old, deprecated
interface (from EDoc version 0.1), and should not be used.</p>
<h3><a name="id61696">1.4
The overview page</a></h3>
<a name="The_overview_page"></a>
<p>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 <span class="code">overview.edoc</span> in the target directory
(typically, this is the <span class="code">doc</span> subdirectory of the application
directory); see <span class="bold_code"><a href="edoc_doclet.html">edoc_doclet</a></span> for details.</p>
<p>The format of the overview file is the same as for EDoc documentation
comments (see <span class="bold_code"><a href="#Introduction">Introduction</a></span>), except that the lines do not
have leading '<span class="code">%</span>' 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 <span class="code">@doc</span>, <span class="code">@version</span>, etc., refer to the
application as a whole; see <span class="bold_code"><a href="#Overview_tags">Overview tags</a></span> for details.</p>
<p>Here is an example of the contents of an overview file:
</p>
<div class="example"><pre> ** this is the overview.doc file for the application 'frob' **
@author R. J. Hacker <rjh@acme.com>
@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,
...</pre></div>
<p>
</p>
<h3><a name="id61191">1.5
Generic tags</a></h3>
<a name="Generic_tags"></a>
<p>
The following tags can be used anywhere within a module:
</p>
<dl>
<dt><strong><span class="code">@clear</span></strong></dt>
<dd>
<a name="gtag-clear"></a><p>This tag causes all tags above it (up to the previous program
construct), to be discarded, including the <span class="code">@clear</span>
tag itself. The text following the tag
is also ignored. <strong>This is typically only useful in code
containing conditional compilation, when preprocessing is turned
on.</strong> (Preprocessing is turned off by default.) E.g., in
</p>
<div class="example"><pre> -ifdef(DEBUG).
%% @doc ...
foo(...) -> ...
-endif.
%% @clear
%% @doc ...
bar(...) -> ...</pre></div>
<p>
the <span class="code">@clear</span> tag makes sure that EDoc does not see
two <span class="code">@doc</span> tags before the function <span class="code">bar</span>,
even if the code for function <span class="code">foo</span> is removed by
preprocessing. (There is no way for EDoc to see what the first
<span class="code">@doc</span> tag "really" belongs to, since preprocessing
strips away all such information.)</p>
</dd>
<dt><strong><span class="code">@docfile</span></strong></dt>
<dd>
<a name="gtag-docfile"></a><p>Reads a plain documentation file (on the same format as an
overview file - see <span class="bold_code"><a href="#The_overview_page">The overview page</a></span> for details), and
uses the tags in that file as if they had been written in place of
the <span class="code">@docfile</span> tag. The content is the name of the file to be
read; leading and trailing whitespace is ignored. See also <span class="bold_code"><a href="#gtag-headerfile">@headerfile</a></span>.</p>
</dd>
<dt><strong><span class="code">@end</span></strong></dt>
<dd>
<a name="gtag-end"></a><p>The text following this tag is always ignored. Use this to
mark the end of the previous tag, when necessary, as e.g. in:
</p>
<div class="example"><pre> %% ----------------------------------
%% ...
%% @doc ...
%% ...
%% @end
%% ----------------------------------</pre></div>
<p>
to avoid including the last "ruler" line in the
<span class="code">@doc</span> tag.</p>
<strong>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.</strong>
</dd>
<dt><strong><span class="code">@headerfile</span></strong></dt>
<dd>
<a name="gtag-headerfile"></a><p>Similar to the <span class="bold_code"><a href="#gtag-docfile">@docfile tag</a></span>, but
reads a file containing Erlang source code - generally this should
be a header file (with the extension <span class="code">.hrl</span>). 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 <span class="code">includes</span> option can be used to specify a search
path (see <span class="bold_code"><a href="edoc.html#read_source-2">edoc:read_source/2</a></span>).</p>
</dd>
<dt><strong><span class="code">@todo</span> (or <span class="code">@TODO</span>)</strong></dt>
<dd>
<a name="gtag-todo"></a><p>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.:
</p>
<div class="example"><pre> %% @TODO Finish writing the documentation.</pre></div>
<p>
or
</p>
<div class="example"><pre> %% @todo Implement <a href="http://www.ietf.org/rfc/rfc2549.txt">RFC 2549</a>.</pre></div>
<p>
These tags can also be written as "<span class="code">TODO:</span>", e.g.:
</p>
<div class="example"><pre> %% TODO: call your mother</pre></div>
<p>
see <span class="bold_code"><a href="#Wiki_notation">Wiki notation</a></span> for more information. To-Do notes are
normally not shown unless the <span class="code">todo</span> option is turned on (see
<span class="bold_code"><a href="edoc.html#get_doc-2">edoc:get_doc/2</a></span>).</p>
</dd>
<dt><strong><span class="code">@type</span></strong></dt>
<dd>
<a name="gtag-type"></a><p>Documents an abstract data type or type alias. The content
consists of a type declaration or definition, optionally
followed by a period ('<span class="code">.</span>') separator and XHTML
text describing the type (i.e., its purpose, use, etc.). There
must be at least one whitespace character between the '<span class="code">.</span>' and
the text. See <span class="bold_code"><a href="#Type_specifications">Type specifications</a></span> for syntax and
examples.
All data type descriptions are placed in a separate section of
the documentation, regardless of where the tags occur.</p>
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 <span class="bold_code"><a href="#Type_specifications">Type specifications</a></span> for examples.</dd>
</dl>
<p>
</p>
<h3><a name="id61227">1.6
Overview tags</a></h3>
<a name="Overview_tags"></a>
<p>
The following tags can be used in an overview file.
</p>
<dl>
<dt><strong><span class="code">@author</span></strong></dt>
<dd>
<a name="otag-author"></a><p>See the <span class="bold_code"><a href="#mtag-author">@author module tag</a></span> for
details.</p>
</dd>
<dt><strong><span class="code">@copyright</span></strong></dt>
<dd>
<a name="otag-copyright"></a><p>See the <span class="bold_code"><a href="#mtag-copyright">@copyright module tag</a></span>
for details.</p>
</dd>
<dt><strong><span class="code">@doc</span></strong></dt>
<dd>
<a name="otag-doc"></a><p>See the <span class="bold_code"><a href="#mtag-doc">@doc module tag</a></span> for
details.</p>
</dd>
<dt><strong><span class="code">@reference</span></strong></dt>
<dd>
<a name="otag-reference"></a><p>See the <span class="bold_code"><a href="#mtag-reference">@reference module tag</a></span>
for details.</p>
</dd>
<dt><strong><span class="code">@see</span></strong></dt>
<dd>
<a name="otag-see"></a><p>See the <span class="bold_code"><a href="#mtag-see">@see module tag</a></span> for
details.</p>
</dd>
<dt><strong><span class="code">@since</span></strong></dt>
<dd>
<a name="otag-since"></a><p>See the <span class="bold_code"><a href="#mtag-since">@since module tag</a></span> for
details.</p>
</dd>
<dt><strong><span class="code">@title</span></strong></dt>
<dd>
<a name="otag-title"></a><p>Specifies a title for the overview page. This tag can
<strong>only</strong> be used in an overview file. The content can be
arbitrary text.</p>
</dd>
<dt><strong><span class="code">@version</span></strong></dt>
<dd>
<a name="otag-version"></a><p>See the <span class="bold_code"><a href="#mtag-version">@version module
tag</a></span> for details.</p>
</dd>
</dl>
<p>
</p>
<h3><a name="id61330">1.7
Module tags</a></h3>
<a name="Module_tags"></a>
<p>
The following tags can be used before a module declaration:
</p>
<dl>
<dt><strong><span class="code">@author</span></strong></dt>
<dd>
<a name="mtag-author"></a><p>Specifies the name of an author, along with contact
information. An e-mail address can be given within <span class="code"><...></span>
delimiters, and a URI within <span class="code">[...]</span> delimiters. Both e-mail and
URI are optional, and any surrounding whitespace is stripped from
all strings.</p>
<p>The name is the first nonempty string that is not within <span class="code"><...></span>
or <span class="code">[...]</span>, 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 <span class="code"><...></span> section is present, but
the name string contains an '<span class="code">@</span>' character, it is assumed to be
an e-mail address. Not both name and e-mail may be left out.</p>
Examples:
<div class="example"><pre> %% @author Richard Carlsson</pre></div>
<div class="example"><pre> %% @author Richard Carlsson <carlsson.richard@gmail.com>
%% [http://user.it.uu.se/~richardc/]</pre></div>
<div class="example"><pre> %% @author <carlsson.richard@gmail.com></pre></div>
<div class="example"><pre> %% @author carlsson.richard@gmail.com [http://user.it.uu.se/~richardc/]</pre></div>
<p>
</p>
</dd>
<dt><strong><span class="code">@copyright</span></strong></dt>
<dd>
<a name="mtag-copyright"></a><p>Specifies the module copyrights. The content can be
arbitrary text; for example:
</p>
<div class="example"><pre> %% @copyright 2001-2003 Richard Carlsson</pre></div>
<p>
</p>
</dd>
<dt><strong><span class="code">@deprecated</span></strong></dt>
<dd>
<a name="mtag-deprecated"></a><p>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 <span class="code">{@link}</span> reference to a
replacement; as in:
</p>
<div class="example"><pre> %% @deprecated Please use the module {@link foo} instead.</pre></div>
<p>
</p>
</dd>
<dt><strong><span class="code">@doc</span></strong></dt>
<dd>
<a name="mtag-doc"></a><p>Describes the module, using well-formed XHTML text. The
first sentence is used as a summary (see the
<span class="bold_code"><a href="#ftag-doc">@doc function tag</a></span> for details). For
example.:
</p>
<div class="example"><pre> %% @doc This is a <em>very</em> useful module. It is ...</pre></div>
</dd>
<dt><strong><span class="code">@hidden</span></strong></dt>
<dd>
<a name="mtag-hidden"></a><p>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.</p>
</dd>
<dt><strong><span class="code">@private</span></strong></dt>
<dd>
<a name="mtag-private"></a><p>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.</p>
</dd>
<dt><strong><span class="code">@reference</span></strong></dt>
<dd>
<a name="mtag-reference"></a><p>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:
</p>
<div class="example"><pre> %% @reference Pratchett, T., <em>Interesting Times</em>,
%% Victor Gollancz Ltd, 1994.</pre></div>
<div class="example"><pre> %% @reference See <a href="www.google.com">Google</a> for
%% more information.</pre></div>
<p>
</p>
</dd>
<dt><strong><span class="code">@see</span></strong></dt>
<dd>
<a name="mtag-see"></a><p>See the <span class="bold_code"><a href="#ftag-see">@see function tag</a></span>
for details.</p>
</dd>
<dt><strong><span class="code">@since</span></strong></dt>
<dd>
<a name="mtag-since"></a><p>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.</p>
</dd>
<dt><strong><span class="code">@version</span></strong></dt>
<dd>
<a name="mtag-version"></a><p>Specifies the module version. The content can be arbitrary
text.</p>
</dd>
</dl>
<p>
</p>
<h3><a name="id63302">1.8
Function tags</a></h3>
<a name="Function_tags"></a>
<p>
The following tags can be used before a function definition:
</p>
<dl>
<dt><strong><span class="code">@deprecated</span></strong></dt>
<dd>
<a name="ftag-deprecated"></a><p>See the <span class="bold_code"><a href="#mtag-deprecated">@deprecated
module tag</a></span> for details.</p>
</dd>
<dt><strong><span class="code">@doc</span></strong></dt>
<dd>
<a name="ftag-doc"></a><p>XHTML text describing the function. The first
sentence of the text is used as a quick summary; this ends at
the first period character ('<span class="code">.</span>') or exclamation mark
('<span class="code">!</span>') 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)</p>
</dd>
<dt><strong><span class="code">@equiv</span></strong></dt>
<dd>
<a name="ftag-equiv"></a><p>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 <span class="code">@doc</span>. </p>
</dd>
<dt><strong><span class="code">@hidden</span></strong></dt>
<dd>
<a name="ftag-hidden"></a><p>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.</p>
</dd>
<dt><strong><span class="code">@private</span></strong></dt>
<dd>
<a name="ftag-private"></a><p>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 <span class="code">spawn</span>. (Non-exported functions are
always "private".) The content can be used as a comment; it is
ignored by EDoc.</p>
</dd>
<dt><strong><span class="code">@see</span></strong></dt>
<dd>
<a name="ftag-see"></a><p>Make a reference to a module, function, datatype, or
application. (See <span class="bold_code"><a href="#References">References</a></span>.)
The content consists of a reference, optionally followed by a
period ('<span class="code">.</span>'), one or more whitespace characters, and
XHTML text to be used for the label; for example "<span class="code">@see edoc</span>" or
"<span class="code">@see edoc. <b>EDoc</b></span>". If no label text is specified, the
reference itself is used as the label.</p>
</dd>
<dt><strong><span class="code">@since</span></strong></dt>
<dd>
<a name="ftag-since"></a><p>Specifies in what version of the module the function was
introduced; cf. the
<span class="bold_code"><a href="#mtag-version">@version
module tag</a></span>. The content can be arbitrary text.</p>
</dd>
<dt><strong><span class="code">@spec</span></strong></dt>
<dd>
<a name="ftag-spec"></a><p>Used to specify the function type; see <span class="bold_code"><a href="#Type_specifications">Type
specifications</a></span> for syntax details. 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.</p>
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 <span class="bold_code"><a href="#Type_specifications">Type specifications</a></span> for examples.</dd>
<dt><strong><span class="code">@throws</span></strong></dt>
<dd>
<a name="ftag-throws"></a><p>Specifies which types of terms may be thrown by the
function, if its execution terminates abruptly due to a call to
<span class="code">erlang:throw(Term)</span>. The content is a type expression (see <span class="bold_code"><a href="#Type_specifications">Type specifications</a></span>), and can be a union type.</p>
Note that exceptions of type <span class="code">exit</span> (as caused by calls to
<span class="code">erlang:exit(Term)</span>) and <span class="code">error</span> (run-time errors such as <span class="code">badarg</span>
or <span class="code">badarith</span>) are not viewed as part of the normal interface of
the function, and cannot be documented with the <span class="code">@throws</span> tag.</dd>
<dt><strong><span class="code">@type</span></strong></dt>
<dd>
<a name="ftag-type"></a><p>See the <span class="bold_code"><a href="#gtag-type">@type generic tag</a></span>
for details. Placing a <span class="code">@type</span> tag by a function
definition may be convenient, but does not affect where the
description is placed in the generated documentation.</p>
</dd>
</dl>
<p>
</p>
<h3><a name="id64690">1.9
References</a></h3>
<a name="References"></a>
<p>
In several contexts (<span class="code">@see</span> tags, <span class="code">@link</span> 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:
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle"><strong>Reference syntax</strong></td>
<td align="left" valign="middle"><strong>Example</strong></td>
<td align="left" valign="middle"><strong>Scope</strong></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">Module</span></td>
<td align="left" valign="middle">
<span class="bold_code"><a href="edoc_run.html">edoc_run</a></span>, <span class="code">erl.lang.list</span>
</td>
<td align="left" valign="middle">Global</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">Package.*</span></td>
<td align="left" valign="middle"><span class="code">erl.lang.*</span></td>
<td align="left" valign="middle">Global</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">Function/Arity</span></td>
<td align="left" valign="middle"><span class="code">file/2</span></td>
<td align="left" valign="middle">Within module</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">Module:Function/Arity</span></td>
<td align="left" valign="middle"><span class="bold_code"><a href="edoc.html#application-2">edoc:application/2</a></span></td>
<td align="left" valign="middle">Global</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">Type()</span></td>
<td align="left" valign="middle"><span class="code">filename()</span></td>
<td align="left" valign="middle">Within module</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">Module:Type()</span></td>
<td align="left" valign="middle"><span class="bold_code"><a href="edoc.html#type-edoc_module">edoc:edoc_module()</a></span></td>
<td align="left" valign="middle">Global</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">//Application</span></td>
<td align="left" valign="middle"><span class="bold_code"><a href="javascript:erlhref('../../../../doc/../','edoc','index.html');">edoc</a></span></td>
<td align="left" valign="middle">Global</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">//Application/Module</span></td>
<td align="left" valign="middle"><span class="bold_code"><a href="javascript:erlhref('../../../../doc/../','edoc','edoc_doclet.html');">edoc_doclet(3)</a></span></td>
<td align="left" valign="middle">Global</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">//Application/Module:Function/Arity</span></td>
<td align="left" valign="middle"><span class="bold_code"><a href="javascript:erlhref('../../../../doc/../','edoc','edoc_run.html#file-1');">edoc_run:file/1</a></span></td>
<td align="left" valign="middle">Global</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">//Application/Module:Type()</span></td>
<td align="left" valign="middle"><span class="bold_code"><a href="javascript:erlhref('../../../../doc/../','edoc','edoc.html#type-edoc_module');">edoc:edoc_module()</a></span></td>
<td align="left" valign="middle">Global</td>
</tr>
</table>
<em>Table
1.1:
reference syntax</em><p>
</p>
<p>EDoc will resolve references using the information it finds in
<span class="code">edoc-info</span>-files at the locations specified with the <span class="code">doc_path</span>
option. EDoc will automatically (and somewhat intelligently) try to find
any local <span class="code">edoc-info</span>-files using the current code path, and add them to
the end of the <span class="code">doc_path</span> list. The target doc-directory is also
searched for an existing info file; this allows documentation to be
built incrementally. (Use the <span class="code">new</span> option to ignore any old info
file.)</p>
<p>Note that if the name of a module, function or datatype is explicitly
qualified with an application (as in "<span class="code">//edoc/edoc_run</span>"), 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 "<span class="code">fred</span>" as
"<span class="code">//foo/fred</span>" without accidentally getting a reference to
"<span class="code">//bar/fred</span>". 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.</p>
<p>Note that module-local references such as <span class="code">file/2</span> 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.</p>
<h3><a name="id60973">1.10
Notes on XHTML</a></h3>
<a name="Notes_on_XHTML"></a>
<p>
In several places, XHTML markup can be used in the documentation
text, in particular in <span class="code">@doc</span> tags. The main differences from
HTML are the following:
</p>
<ul>
<li><p>All elements must have explicit start and end tags, and be
correctly nested. This means that you cannot e.g. write a
<span class="code"><li></span> tag without also writing a corresponding <span class="code"></li></span>
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.</p></li>
<li><p>XHTML tag and attribute names should always be lower-case.</p></li>
<li><p>Attributes must be quoted, as in e.g. <span class="code"><a
name="top"></span>.</p></li>
</ul>
<p>
To write an element like the HTML <span class="code"><br></span>, which has no actual content,
you can write either the full <span class="code"><br></br></span>, or better, use the XHTML
abbreviated form <span class="code"><br/></span>.</p>
<p>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 <span class="bold_code"><a href="#Wiki_notation">Wiki notation</a></span> for details.</p>
<p>The HTML heading tags <span class="code">h1</span> and <span class="code">h2</span> are reserved for use by EDoc.
Headings in documentation source code should start at <span class="code">h3</span>. There is
however a special syntax for writing headings which avoids using
specific level numbers altogether; see <span class="bold_code"><a href="#Headings">Headings</a></span> for details.</p>
<p>EDoc uses <span class="bold_code"><a href="javascript:erlhref('../../../../doc/../','xmerl','index.html');">XMerL</a></span> to parse and export XML markup.</p>
<h3><a name="id61084">1.11
Wiki notation</a></h3>
<a name="Wiki_notation"></a>
<p>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" (<span class="bold_code"><a href="http://en.wikipedia.org/wiki/Wiki">http://en.wikipedia.org/wiki/Wiki</a></span>)
notation is intended to make it easier to write source code
documentation.</p>
<h4>Empty lines separate paragraphs</h4>
<a name="Empty_lines_separate_paragraphs"></a>
<p>
Leaving an empty line in XHTML text (i.e., a line which except for
any leading start-of-comment '<span class="code">%</span>' characters contains only
whitespace), will make EDoc split the text before and
after the empty line into separate paragraphs. For example:
</p>
<div class="example"><pre> %% @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.</pre></div>
<p>
will generate the following text:
</p>
<p>This will all be part of the first paragraph. It can
stretch over several lines and contain <strong>any XHTML markup</strong>.</p>
<p>
This is the second paragraph. The above line is regarded as "empty" by
EDoc, even though it ends with a space.</p>
<p>Paragraph splitting takes place after the actual XHTML parsing. It only
affects block-level text, and not e.g., text within <span class="code"><pre></span> markup, or
text that is already within <span class="code"><p></span> markup.</p>
<h4>Headings</h4>
<a name="Headings"></a>
<p>
Section headings, sub-headings, and sub-sub-headings, can be written
using the following notation:
</p>
<div class="example"><pre> == Heading ==
=== Sub-heading ===
==== Sub-sub-heading ====</pre></div>
<p>
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.,
</p>
<div class="example"><pre> == Concerning Hobbits ==</pre></div>
<p>
is equivalent to
</p>
<div class="example"><pre> <h3><a name="Concerning_Hobbits">Concerning Hobbits</a></h3></pre></div>
<p>
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.</p>
<p>A hypertext link to a heading written this way can be created using the
<span class="code">@section</span> macro, which transforms the argument text into a label as
described above. E.g.,
</p>
<div class="example"><pre> {@section Concerning Hobbits}</pre></div>
<p>
is equivalent to writing
</p>
<div class="example"><pre> <a href="#Concerning_Hobbits">Concerning Hobbits</a></pre></div>
<p>The above expansions take place before XML parsing.</p>
<h4>External links</h4>
<a name="External_links"></a>
<p>Writing a URL within brackets, as in "<span class="code">[http://www.w3c.org/]</span>", will
generate a hyperlink such as <span class="bold_code"><a href="http://www.w3c.org/">http://www.w3c.org/</a></span>, using the URL both
for the destination and the label of the reference, equivalent to writing
"<span class="code"><a href="http://www.w3c.org/"><tt>http://www.w3c.org/</tt></a></span>". This
short-hand keeps external URL references short and readable. The
recognized protocols are <span class="code">http</span>, <span class="code">ftp</span>, and <span class="code">file</span>. This expansion takes
place before XML parsing.</p>
<h4>TODO-notes</h4>
<a name="TODO-notes"></a>
<p>Lines that begin with the text "<span class="code">TODO:</span>" (the colon is required) are
recognized as tags, as if they had been written as "<span class="code">@todo ...</span>" (see <span class="bold_code"><a href="#gtag-todo">@todo tags</a></span> for further details).</p>
<h4>Verbatim quoting</h4>
<a name="Verbatim_quoting"></a>
<p>In XHTML text, the '<span class="code">`</span>' character (Unicode <span class="code">000060</span>,
known as "grave accent" or "back-quote") can be used for verbatim
quoting. This expansion takes place before XML parsing.</p>
<ul>
<li>
<p>A character sequence "<span class="code">`...'</span>" or
"<span class="code">``...''</span>" will be expanded to
"<span class="code"><code>...</code></span>", where all occurrences of the special XML
characters '<span class="code"><</span>' and '<span class="code">&</span>' (and for completeness, also '<span class="code">></span>') in
the quoted text have been escaped to "<span class="code">&lt;</span>", "<span class="code">&amp;</span>", and
"<span class="code">&gt;</span>", respectively.
All whitespace is stripped from the beginning and end of the
quoted text.</p>
<p>Double back-quotes "<span class="code">``...''</span>" can be used
to quote text containing single '<span class="code">'</span>' characters. The automatic
stripping of any surrounding whitespace makes it possible to write
things like "<span class="code">`` 'foo@bar' ''</span>".</p>
To quote text containing "<span class="code">''</span>" verbatim,
explicit <span class="code"><code></span> markup or similar must be used.</li>
<li><p>A character sequence "<span class="code">```...'''</span>"
will be expanded to "<span class="code"><pre><![CDATA[...]]></pre></span>", 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.</p></li>
<li><p>To produce a single '<span class="code">`</span>'-character in XML
without beginning a new quote, you can write "<span class="code">`'</span>"
(no space between the '<span class="code">`</span>' and the '<span class="code">'</span>').
You can of course also use the XML character entity
"<span class="code">&#x60;</span>".</p></li>
</ul>
<p>
Examples:
</p>
<div class="example"><pre> %% @doc ...where the variable `Foo' refers to...</pre></div>
<div class="example"><pre> %% @doc ...returns the atom `` 'foo@erlang.org' ''...</pre></div>
<div class="example"><pre>
%% @doc ...use the command ```erl -name foo''' to...</pre></div>
<div class="example"><pre>
%% @doc ...as in the following code:
%% ```f(X) ->
%% case X of
%% ...
%% end'''</pre></div>
<div class="example"><pre>
%% @doc ...or in the following:
%% ```
%% g(X) ->
%% fun () -> ... end
%% '''</pre></div>
<p>
</p>
<h3><a name="id58238">1.12
Macro expansion</a></h3>
<a name="Macro_expansion"></a>
<p>
Before the content of a tag is parsed, the text undergoes <strong>macro
expansion</strong>. The syntax for macro calls is:
</p>
<div class="example"><pre>
{@name}</pre></div>
<p>
or
</p>
<div class="example"><pre>
{@name argument}</pre></div>
<p>
where <strong>name</strong> and <strong>argument</strong> 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 "<span class="code">{@</span>" and
"<span class="code">}</span>" delimiters must be balanced.</p>
<p>The argument text is first expanded in the current environment, and
the result is bound to the <strong>macro parameter</strong>, written
<span class="code">{@?}</span>. (If no argument is given, <span class="code">{@?}</span> 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.</p>
<h4>User-defined macros</h4>
<a name="User-defined_macros"></a>
<p>Users can define their own macros by using the <span class="code">def</span> EDoc
option; see <span class="bold_code"><a href="edoc.html#file-2">edoc:file/2</a></span> and <span class="bold_code"><a href="edoc.html#get_doc-2">edoc:get_doc/2</a></span> for more
information. User-defined macros override predefined macros.</p>
<h4>Predefined macros</h4>
<a name="Predefined_macros"></a>
<dl>
<dt><strong><span class="code">{@date}</span></strong></dt>
<dd>
<a name="predefmacro-date"></a><p>Expands to the current date, as "<span class="code">Month Day Year</span>",
e.g. "Dec 6 2012".</p>
</dd>
<dt><strong><span class="code">{@docRoot}</span></strong></dt>
<dd>
<a name="predefmacro-docRoot"></a><p>Expands to the relative URL path (such as
<span class="code">"../../.."</span>) from the current page to the root
directory of the generated documentation. This can be used to
create XHTML references such as <span class="code"><img
src="{@docRoot}/images/logo.jpeg"></span> 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),
<span class="code">{@docRoot}</span> will always resolve to the empty
string.</p>
</dd>
<dt><strong><span class="code">{@link reference.
description}</span></strong></dt>
<dd>
<a name="predefmacro-link"></a><p>This creates a hypertext link; cf. the
<span class="bold_code"><a href="#ftag-see">@see function tag</a></span> above for
details. The description text (including the period separator)
is optional; if no text is given, the reference itself is
used. For example, <span class="code">{@link edoc:file/2}</span> creates the
link <span class="bold_code"><a href="edoc.html#file-2">edoc:file/2</a></span>, and <span class="code">{@link edoc:file/2. <em>this link</em>}</span>
creates <span class="bold_code"><a href="edoc.html#file-2">this link</a></span>.</p>
</dd>
<dt><strong><span class="code">{@module}</span></strong></dt>
<dd>
<a name="predefmacro-module"></a><p>Expands to the name of the current module. Only defined when a
module is being processed.</p>
</dd>
<dt><strong><span class="code">{@package}</span></strong></dt>
<dd>
<a name="predefmacro-package"></a><p>Expands to the name of the current package.</p>
</dd>
<dt><strong><span class="code">{@section
heading}</span></strong></dt>
<dd>
<a name="predefmacro-section"></a><p>Expands to a hypertext link to the specified section heading;
see <span class="bold_code"><a href="#Headings">Headings</a></span> for more information.</p>
</dd>
<dt><strong><span class="code">{@time}</span></strong></dt>
<dd>
<a name="predefmacro-time"></a><p>Expands to the current time, as "<span class="code">Hr:Min:Sec</span>",
e.g. "18:52:27".</p>
</dd>
<dt><strong><span class="code">{@type
type-expression}</span></strong></dt>
<dd>
<a name="predefmacro-type"></a><p>Formats a type expression within <span class="code"><code>...</code></span>
markup and with hypertext links for data types. For example,
<span class="code">{@type {options, List::edoc:option_list()@}}</span>
generates "<span class="code">{options, List::edoc:option_list()}</span>". (Cf.
<span class="bold_code"><a href="#Escape_sequences">Escape sequences</a></span>.)</p>
</dd>
<dt><strong><span class="code">{@version}</span></strong></dt>
<dd>
<a name="predefmacro-version"></a><p>Intended for use in <span class="bold_code"><a href="#mtag-version">@version
tags</a></span>. Defaults to a timestamp using <span class="code">{@date}</span> and <span class="code">{@time}</span>.
Typically, this macro is redefined by the user when an official
release of the application is generated.</p>
</dd>
</dl>
<p>
</p>
<h4>Escape sequences</h4>
<a name="Escape_sequences"></a>
<p>
To prevent certain characters from being interpreted as delimiters,
for example to produce the text "<span class="code">{@</span>" in the output, or use a
'<span class="code">}</span>' character in the argument text of a macro call, the
following escape sequences may be used: </p>
<dl>
<dt><strong><span class="code">@{</span></strong></dt>
<dd>
<p>Expands to "<span class="code">{</span>". Example:
</p>
<div class="example"><pre> %% @doc A macro call starts with the sequence "@{@".</pre></div>
<p>
</p>
</dd>
<dt><strong><span class="code">@}</span></strong></dt>
<dd>
<p>Expands to "<span class="code">}</span>". Example:
</p>
<div class="example"><pre> %% @doc ...{@foo ...{Key, Value@}...}...</pre></div>
<p>
</p>
</dd>
<dt><strong><span class="code">@@</span></strong></dt>
<dd>
<p>Expands to "<span class="code">@</span>". Example:
</p>
<div class="example"><pre> %% @doc Contact us at support@@{@hostname}</pre></div>
<p>
Will generate the text "Contact us at support@vaporware.acme.com"
if the macro <span class="code">hostname</span> is bound to
"<span class="code">vaporware.acme.com</span>". Also:
</p>
<div class="example"><pre> %% @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.</pre></div>
<p>
</p>
</dd>
</dl>
<p>
</p>
<h3><a name="id63489">1.13
Type specifications</a></h3>
<a name="Type_specifications"></a>
<h4>Function specifications</h4>
<a name="Function_specifications"></a>
<p><div class="note">
<div class="label">Note</div>
<div class="content"><p>Although the syntax described in the following can still be used
for specifying functions we recommend that Erlang specifications as
described in <span class="bold_code"><a href="javascript:erlhref('../../../../doc/../','doc/reference_manual','typespec.html');"> Types
and Function Specification</a></span> should be added to the source
code instead. This way the analyses of <span class="bold_code"><a href="javascript:erlhref('../../../../doc/../','dialyzer','dialyzer.html');">Dialyzer</a></span>'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 <span class="code">@spec</span> tag followed by a type) with the same name.
</p></div>
</div></p>
<p>The following grammar describes the form of the specifications following
a <span class="code">@spec</span> tag. A '<span class="code">?</span>' suffix implies that the element is optional.
Function types have higher precedence than union types; e.g., "<span class="code">(atom())
-> atom() | integer()</span>" is parsed as <span class="code">((atom()) -> atom()) | integer()</span>,
not as <span class="code">(atom()) -> (atom() | integer())</span>.</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle"><span class="code">Spec</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">FunType "where"? DefList?
| FunctionName FunType "where"? DefList?</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">FunctionName</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">Atom</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">FunType</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">"(" UnionTypes? ")" "->" UnionType</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">UnionTypes</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">UnionType
| UnionType "," UnionTypes</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">UnionType</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">UnionList
| Name "::" UnionList</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">Name</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">Variable</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">UnionList</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">Type
| Type "+" UnionList
| Type "|" UnionList</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">Type</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">TypeVariable
| Atom
| Integer
| Float
| Integer ".." Integer
| FunType
| "fun(" FunType ")"
| "fun(...)"
| "{" UnionTypes? "}"
| "#" Atom "{" Fields? "}"
| "[" "]"
| "[" UnionType "]"
| "[" UnionType "," "..." "]"
| "(" UnionType ")"
| BinType
| TypeName "(" UnionTypes? ")"
| ModuleName ":" TypeName "(" UnionTypes? ")"
| "//" AppName "/" ModuleName ":" TypeName "(" UnionTypes? ")"</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">Fields</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">Field
| Fields "," Fields</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">Field</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">Atom "=" UnionList</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">BinType</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">"<<>>"
| "<<" BaseType ">>"
| "<<" UnitType ">>"
| "<<" BaseType "," UnitType ">>"</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">BaseType</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">"_" ":" Integer</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">UnitType</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">"_" ":" "_" "*" Integer</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">TypeVariable</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">Variable</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">TypeName</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">Atom</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">ModuleName</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">Atom
| ModuleName "." Atom</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">AppName</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">Atom</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">DefList</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">Def
| DefList Def
| DefList "," Def</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">Def</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">TypeVariable "=" UnionList
| TypeName "(" TypeVariables? ")" "=" UnionType</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">TypeVariables</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">TypeVariable
| TypeVariable "," TypeVariables</span></td>
</tr>
</table>
<em>Table
1.2:
specification syntax grammar</em><p>
Examples:
</p>
<div class="example"><pre> -spec my_function(X :: integer()) -> integer().
%% @doc Creates ...</pre></div>
<div class="example"><pre> %% @spec my_function(X::integer()) -> integer()</pre></div>
<div class="example"><pre> %% @spec (X::integer()) -> integer()</pre></div>
<div class="example"><pre> %% @spec sqrt(float()) -> float()</pre></div>
<div class="example"><pre> %% @spec pair(S, T) -> {S, T}</pre></div>
<div class="example"><pre> %% @spec append(List, List) -> List
%% List = [term()]</pre></div>
<div class="example"><pre> %% @spec append(A::List, B::List) -> List
%% List = [Item]
%% Item = term()</pre></div>
<div class="example"><pre> %% @spec open(File::filename()) -> FileDescriptor
%% where
%% filename() = string() + atom(),
%% FileDescriptor = term()</pre></div>
<div class="example"><pre> %% @spec close(graphics:window()) -> ok</pre></div>
<p>The first example shows the recommended way of specifying functions.</p>
<p>In the above examples, <span class="code">X</span>, <span class="code">A</span>, <span class="code">B</span>,
and <span class="code">File</span> are parameter names, used for referring to the
parameters from the documentation text. The <strong>type variables</strong>
<span class="code">S</span>, <span class="code">T</span> and <span class="code">List</span> 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
<span class="code">@type</span> tag to document abstract data types.) If a named type
is defined in another module, it can be referred to as
<span class="code">Module:TypeName(...)</span>. Note that the keyword '<span class="code">where</span>' is optional
before a list of definitions, and that the definitions in the list may
optionally be separated by '<span class="code">,</span>'.</p>
<p>Both the '<span class="code">|</span>' and the '<span class="code">+</span>' character may be
used to separate alternatives in union types; there is no semantic
difference. Note that the notation <span class="code">[Type]</span> means "proper
(nil-terminated) list whose elements all belong to <span class="code">Type</span>";
For example, <span class="code">[atom()|integer()]</span> means the same thing as
<span class="code">[atom()+integer()]</span>, i.e., a proper list of atoms and/or
integers.</p>
<p>If only a type variable is given for a parameter, as in
"<span class="code">pair(S, T) -> ...</span>", the same variable name may implicitly
be used as the parameter name; there is no need to write
"<span class="code">pair(S::S, T::T) -> ...</span>".</p>
<p>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 <span class="code">X1</span>. This way, EDoc
can often produce helpful documentation even for code that does not
contain any annotations at all.</p>
<h4>Type definitions</h4>
<a name="Type_definitions"></a>
<p><div class="note">
<div class="label">Note</div>
<div class="content"><p>Although the syntax described in the following can still be used
for specifying types we recommend that Erlang types as described in
<span class="bold_code"><a href="javascript:erlhref('../../../../doc/../','doc/reference_manual','typespec.html');"> Types and Function
Specification</a></span> should be added to the source code instead.
Erlang types will be used unless there is a type alias with the same
name.</p></div>
</div></p>
<p>The following grammar (see above for auxiliary definitions) describes
the form of the definitions that may follow a <span class="code">@type</span> tag:</p>
<table border="1" cellpadding="2" cellspacing="0"><tr>
<td align="left" valign="middle"><span class="code">Typedef</span></td>
<td align="left" valign="middle">::=</td>
<td align="left" valign="middle"><span class="code">TypeName "(" TypeVariables? ")" DefList?
| TypeName "(" TypeVariables? ")" "=" UnionList DefList?</span></td>
</tr></table>
<em>Table
1.3:
type definition grammar</em><p>
(For a truly abstract data type, no equivalence is specified.) The main
definition may be followed by additional local definitions. Examples:
</p>
<div class="example"><pre> -type my_list(X) :: [X]. %% A special kind of lists ...</pre></div>
<div class="example"><pre> -opaque another_list(X) :: [X].
%% another_list() is a kind of list...</pre></div>
<div class="example"><pre> %% @type myList(X). A special kind of lists ...</pre></div>
<div class="example"><pre> %% @type filename() = string(). Atoms not allowed!</pre></div>
<div class="example"><pre> %% @type thing(A) = {thong, A}
%% A = term().
%% A kind of wrapper type thingy.</pre></div>
<p>The first two examples show the recommended way of specifying types.</p>
<h4>Pre-defined data types</h4>
<a name="Pre-defined_data_types"></a>
<p>
The following data types are predefined by EDoc, and may not be
redefined:
</p>
<div class="example"><pre> any()
arity()
atom()
binary()
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()</pre></div>
<p>
Details:
</p>
<ul>
<li><p><span class="code">any()</span> means "any Erlang data type".
<span class="code">term()</span> is simply an alias for <span class="code">any()</span>.</p></li>
<li><p><span class="code">atom()</span>, <span class="code">binary()</span>,
<span class="code">float()</span>, <span class="code">function()</span>,
<span class="code">integer()</span>, <span class="code">pid()</span>, <span class="code">port()</span>
and <span class="code">reference()</span> are primitive data types of
the Erlang programming language.</p></li>
<li><p><span class="code">boolean()</span> is the subset of <span class="code">atom()</span> consisting
of the atoms <span class="code">true</span> and <span class="code">false</span>.</p></li>
<li><p><span class="code">char()</span> is the subset of <span class="code">integer()</span> representing
Unicode character codes: hex 000000-10FFFF.</p></li>
<li><p><span class="code">tuple()</span> is the set of all tuples <span class="code">{...}</span>.</p></li>
<li><p><span class="code">list(T)</span> is just an alias for <span class="code">[T]</span>; list() is an alias
for <span class="code">list(any())</span>, i.e., <span class="code">[any()]</span>.</p></li>
<li><p><span class="code">nil()</span> is an alias for the empty list <span class="code">[]</span>.</p></li>
<li><p><span class="code">cons(H,T)</span> is the list constructor. This is usually not
used directly. It is possible to recursively define <span class="code">list(T)
:= nil()+cons(T,list(T))</span>.</p></li>
<li><p><span class="code">string()</span> is an alias for <span class="code">[char()]</span>.</p></li>
<li><p><span class="code">deep_string()</span> is recursively defined as
<span class="code">[char()+deep_string()]</span>.</p></li>
<li><p><span class="code">none()</span> means "no data type". E.g., a function
that never returns has type <span class="code">(...) -> none()</span></p></li>
</ul>
<p>
</p>
<h3><a name="id64274">1.14
Acknowledgements</a></h3>
<a name="Acknowledgements"></a>
<p>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.</p>
<p>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.
</p>
</div>
<div class="footer">
<hr>
<p>Copyright © 2006-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
542
