aboutsummaryrefslogtreecommitdiffstats
path: root/lib/edoc/doc/overview.edoc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/edoc/doc/overview.edoc')
-rw-r--r--lib/edoc/doc/overview.edoc1026
1 files changed, 1026 insertions, 0 deletions
diff --git a/lib/edoc/doc/overview.edoc b/lib/edoc/doc/overview.edoc
new file mode 100644
index 0000000000..9b25c17b1f
--- /dev/null
+++ b/lib/edoc/doc/overview.edoc
@@ -0,0 +1,1026 @@
+ -*- html -*-
+
+ EDoc overview page
+
+
+@author Richard Carlsson <[email protected]>
+@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 <[email protected]>
+ @@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 <[email protected]>
+ %% [http://user.it.uu.se/~richardc/]'''
+
+```%% @author <[email protected]>'''
+
+```%% @author [email protected] [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>
+
+</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
+ application. (See {@section References}.)
+ 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} 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.</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} 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} 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 equivalent 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.
+
+ === TODO-notes ===
+
+Lines that begin with the text "`TODO:'" (the colon is required) are
+recognized as tags, as if they had been written as "`@todo ...'" (see <a
+href="#gtag-todo">@todo tags</a> for further details).
+
+ === 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 `` '[email protected]' ''... '''
+
+ <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. User-defined macros override predefined macros.
+
+ === 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>
+
+ <dt><a name="predefmacro-module"><code>@{@module}</code></a></dt>
+ <dd>Expands to the name of the current module. Only defined when a
+ module is being processed.</dd>
+
+ <dt><a name="predefmacro-package"><code>@{@package}</code></a></dt>
+ <dd>Expands to the name of the current package.</dd>
+
+ <dt><a name="predefmacro-section"><code>@{@section
+ <em>heading</em>}</code></a></dt>
+ <dd>Expands to a hypertext link to the specified section heading;
+ see {@section Headings} for more information.</dd>
+
+ <dt><a name="predefmacro-time"><code>@{@time}</code></a></dt>
+ <dd>Expands to the current time, as "<tt>Hr:Min:Sec</tt>",
+ e.g. "{@time}".</dd>
+
+ <dt><a name="predefmacro-type"><code>@{@type
+ <em>type-expression</em>}</code></a></dt>
+ <dd>Formats a type expression within `<code>...</code>'
+ markup and with hypertext links for data types. For example,
+ <code>@{@type {options, List::edoc:option_list()@@}}</code>
+ generates "{@type {options, List::edoc:option_list()@}}". (Cf.
+ {@section Escape sequences}.)</dd>
+
+ <dt><a name="predefmacro-version"><code>@{@version}</code></a></dt>
+ <dd>Intended for use in <a href="#mtag-version">`@version'
+ tags</a>. Defaults to a timestamp using `@{@date}' and `@{@time}'.
+ Typically, this macro is redefined by the user when an official
+ release of the application is generated.</dd>
+</dl>
+
+ === Escape sequences ===
+
+To prevent certain characters from being interpreted as delimiters,
+for example to produce the text "<code>@{@</code>" in the output, or use a
+'`}'' character in the argument text of a macro call, the
+following escape sequences may be used: <dl>
+ <dt><code>@@{</code></dt>
+ <dd>Expands to "`{'". Example:
+```
+ %% @doc A macro call starts with the sequence "@@@{@".'''
+ </dd>
+ <dt><code>@@}</code></dt>
+ <dd>Expands to "`}'". Example:
+```
+ %% @doc ...@{@foo ...{Key, Value@@}...}...'''
+ </dd>
+ <dt><code>@@@@</code></dt>
+ <dd>Expands to "`@'". Example:
+```
+ %% @doc Contact us at support@@@@@{@hostname}'''
+ Will generate the text "Contact us at [email protected]"
+ if the macro `hostname' is bound to
+ "`vaporware.acme.com'". Also:
+```
+ %% @doc You might want to write something like
+ %% @@@@foo that will expand to @@foo and does not start
+ %% a new tag even if it appears first in a line.'''
+ </dd>
+</dl>
+
+
+== Type specifications ==
+
+ === Function specifications ===
+
+The following grammar describes the form of the specifications following
+a `@spec' tag. A '`?'' suffix implies that the element is optional.
+Function types have higher precedence than union types; e.g., "`(atom())
+-> atom() | integer()'" is parsed as `((atom()) -> atom()) | integer()',
+not as `(atom()) -> (atom() | integer())'.
+
+<table summary="specification syntax grammar">
+<tbody valign="baseline">
+ <tr>
+ <td><code>Spec</code></td>
+ <td>::=</td>
+ <td><code>FunType "where"? DefList?
+ <br/>| FunctionName FunType "where"? DefList?</code></td>
+ </tr>
+ <tr>
+ <td><code>FunctionName</code></td>
+ <td>::=</td>
+ <td><code>Atom</code></td>
+ </tr>
+ <tr>
+ <td><code>FunType</code></td>
+ <td>::=</td>
+ <td><code>"(" UnionTypes? ")" "->" UnionType</code></td>
+ </tr>
+ <tr>
+ <td><code>UnionTypes</code></td>
+ <td>::=</td>
+ <td><code>UnionType
+ <br/>| UnionType "," UnionTypes</code></td>
+ </tr>
+ <tr>
+ <td><code>UnionType</code></td>
+ <td>::=</td>
+ <td><code>UnionList
+ <br/>| Name "::" UnionList</code></td>
+ </tr>
+ <tr>
+ <td><code>Name</code></td>
+ <td>::=</td>
+ <td><code>Variable</code></td>
+ </tr>
+ <tr>
+ <td><code>UnionList</code></td>
+ <td>::=</td>
+ <td><code>Type
+ <br/>| Type "+" UnionList
+ <br/>| Type "|" UnionList</code></td>
+ </tr>
+ <tr>
+ <td><code>Type</code></td>
+ <td>::=</td>
+ <td><code>TypeVariable
+ <br/>| Atom
+ <br/>| Integer
+ <br/>| Float
+ <br/>| FunType
+ <br/>| "{" UnionTypes? "}"
+ <br/>| "[" "]"
+ <br/>| "[" UnionType "]"
+ <br/>| "(" UnionType ")"
+ <br/>| TypeName "(" UnionTypes? ")"
+ <br/>| ModuleName ":" TypeName "(" UnionTypes? ")"
+ <br/>| "//" AppName "/" ModuleName ":" TypeName "(" UnionTypes? ")"</code></td>
+ </tr>
+ <tr>
+ <td><code>TypeVariable</code></td>
+ <td>::=</td>
+ <td><code>Variable</code></td>
+ </tr>
+ <tr>
+ <td><code>TypeName</code></td>
+ <td>::=</td>
+ <td><code>Atom</code></td>
+ </tr>
+ <tr>
+ <td><code>ModuleName</code></td>
+ <td>::=</td>
+ <td><code>Atom
+ <br/>| ModuleName "." Atom</code></td>
+ </tr>
+ <tr>
+ <td><code>AppName</code></td>
+ <td>::=</td>
+ <td><code>Atom</code></td>
+ </tr>
+ <tr>
+ <td><code>DefList</code></td>
+ <td>::=</td>
+ <td><code>Def
+ <br/>| DefList Def
+ <br/>| DefList "," Def</code></td>
+ </tr>
+ <tr>
+ <td><code>Def</code></td>
+ <td>::=</td>
+ <td><code>TypeVariable "=" UnionType
+ <br/>| TypeName "(" TypeVariables? ")" "=" UnionType</code></td>
+ </tr>
+ <tr>
+ <td><code>TypeVariables</code></td>
+ <td>::=</td>
+ <td><code>TypeVariable
+ <br/>| TypeVariable "," TypeVariables</code></td>
+ </tr>
+</tbody>
+</table>
+
+
+Examples:
+```
+ %% @spec my_function(X::integer()) -> integer()'''
+```
+ %% @spec (X::integer()) -> integer()'''
+```
+ %% @spec sqrt(float()) -> float()'''
+```
+ %% @spec pair(S, T) -> {S, T}'''
+```
+ %% @spec append(List, List) -> List
+ %% List = [term()]'''
+```
+ %% @spec append(A::List, B::List) -> List
+ %% List = [Item]
+ %% Item = term()'''
+```
+ %% @spec open(File::filename()) -> FileDescriptor
+ %% where
+ %% filename() = string() + atom(),
+ %% FileDescriptor = term()'''
+```
+ %% @spec close(graphics:window()) -> ok'''
+
+In the above examples, `X', `A', `B',
+and `File' are parameter names, used for referring to the
+parameters from the documentation text. The <em>type variables</em>
+`S', `T' and `List' are used to
+simplify the type specifications, and may be supplied with
+definitions. It is also possible to give definitions for named types,
+which means that the name is simply an alias. (Use the
+`@type' tag to document abstract data types.) If a named type
+is defined in another module, it can be referred to as
+`Module:TypeName(...)'. Note that the keyword '`where'' is optional
+before a list of definitions, and that the definitions in the list may
+optionally be separated by '`,''.
+
+Both the '`|'' and the '`+'' character may be
+used to separate alternatives in union types; there is no semantic
+difference. Note that the notation `[Type]' means "proper
+(nil-terminated) list whose elements all belong to `Type'";
+For example, `[atom()|integer()]' means the same thing as
+`[atom()+integer()]', i.e., a proper list of atoms and/or
+integers.
+
+If only a type variable is given for a parameter, as in
+"`pair(S, T) -> ...'", the same variable name may implicitly
+be used as the parameter name; there is no need to write
+"`pair(S::S, T::T) -> ...'".
+
+EDoc automatically extracts possible parameter names from the source
+code, to be used if no parameter name is given in the specification (or
+if the specification is missing altogether). If this fails, EDoc will
+generate a dummy parameter name, such as `X1'. This way, EDoc
+can often produce helpful documentation even for code that does not
+contain any annotations at all.
+
+ === Type definitions ===
+
+The following grammar (see above for auxiliary definitions) describes
+the form of the definitions that may follow a `@type' tag:
+
+<table summary="type definition grammar">
+<tbody valign="baseline">
+ <tr>
+ <td><code>Typedef</code></td>
+ <td>::=</td>
+ <td><code>TypeName "(" TypeVariables? ")" DefList?
+ <br/>| TypeName "(" TypeVariables? ")" "=" UnionType DefList?</code></td>
+ </tr>
+</tbody>
+</table>
+
+(For a truly abstract data type, no equivalence is specified.) The main
+definition may be followed by additional local definitions. Examples:
+```
+ %% @type myList(X). A special kind of lists ...'''
+```
+ %% @type filename() = string(). Atoms not allowed!'''
+```
+ %% @type thing(A) = {thong, A}
+ %% A = term().
+ %% A kind of wrapper type thingy.'''
+
+
+ === Pre-defined data types ===
+
+The following data types are predefined by EDoc, and may not be
+redefined:
+```
+ any()
+ atom()
+ binary()
+ bool()
+ char()
+ cons()
+ deep_string()
+ float()
+ function()
+ integer()
+ list()
+ nil()
+ none()
+ number()
+ pid()
+ port()
+ reference()
+ string()
+ term()
+ tuple()
+'''
+Details:
+<ul>
+ <li>`any()' means "any Erlang data type".
+ `term()' is simply an alias for `any()'.</li>
+ <li>`atom()', `binary()',
+ `float()', `function()',
+ `integer()', `pid()', `port()'
+ and `reference()' are primitive data types of
+ the Erlang programming language.</li>
+ <li>`bool()' is the subset of `atom()' consisting
+ of the atoms `true' and `false'.</li>
+ <li>`char()' is a subset of
+ `integer()' representing character codes.</li>
+ <li>`tuple()' is the set of all tuples `{...}'.</li>
+ <li>`list(T)' is just an alias for `[T]'.</li>
+ <li>`nil()' is an alias for the empty list `[]'.</li>
+ <li>`cons(H,T)' is the list constructor. This is usually not
+ used directly. It is possible to recursively define `list(T)
+ := nil()+cons(T,list(T))'.</li>
+ <li>`string()' is an alias for `[char()]'.</li>
+ <li>`deep_string()' is recursively defined as
+ `[char()+deep_string()]'.</li>
+ <li>`none()' means "no data type". E.g., a function
+ that never returns has type `(...) -> none()'</li>
+</ul>
+
+
+== Acknowledgements ==
+
+Since the first version of EDoc, several people have come up with
+suggestions (Luke Gorrie, Joe Armstrong, Erik Stenman, Sean Hinde, Ulf
+Wiger, ...), and some have even submitted code to demonstrate their
+ideas (Vlad Dumitrescu, Johan Blom, Vijay Hirani, ...). None of that
+code was actually included in the Great Rewriting that followed the
+initial public release (EDoc version 0.1), but most of the central
+points were addressed in the new system, such as better modularization
+and possibility to plug in different layout engines, and making EDoc
+understand the application directory layout.
+
+It is now getting too hard to keep track of all the people who have made
+further suggestions or submitted bug reports, but your input is always
+appreciated. Thank you.