- {@section Introduction}
- {@section Running EDoc}
- {@section The overview page}
- {@section Generic tags}
- {@section Overview tags}
- {@section Module tags}
- {@section Function tags}
- {@section References}
- {@section Notes on XHTML}
- {@section Wiki notation}
- {@section Macro expansion}
- {@section Type specifications}
- {@section Acknowledgements}
- {@link edoc:application/2}: Creates documentation for a typical Erlang application.
- {@link edoc:packages/2}: Creates documentation for one or more packages, automatically locating source files.
- {@link edoc:files/2}: Creates documentation for a specified set of source files.
- {@link edoc:run/3}: General interface function; the common back-end for the above functions. Options are documented here.
- `@clear'
- 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. This is typically only useful in code containing conditional compilation, when preprocessing is turned on. (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.)
- `@docfile'
- 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 `@headerfile'.
- `@end'
- 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. 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.
- `@headerfile'
- Similar to the `@docfile' tag, 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}).
- `@todo' (or `@TODO')
- 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 RFC 2549.''' 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}).
- `@type'
- 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. 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 {@section Type specifications} for examples.
- `@author'
- See the `@author' module tag for details.
- `@copyright'
- See the `@copyright' module tag for details.
- `@doc'
- See the `@doc' module tag for details.
- `@reference'
- See the `@reference' module tag for details.
- `@see'
- See the `@see' module tag for details.
- `@since'
- See the `@since' module tag for details.
- `@title'
- Specifies a title for the overview page. This tag can only be used in an overview file. The content can be arbitrary text.
- `@version'
- See the `@version' module tag for details.
- `@author'
- 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
- `@copyright'
- Specifies the module copyrights. The content can be arbitrary text; for example: ``` %% @copyright 2001-2003 Richard Carlsson'''
- `@deprecated'
- 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.'''
- `@doc'
- Describes the module, using well-formed XHTML text. The first sentence is used as a summary (see the `@doc' function tag for details). For example.: ```%% @doc This is a very useful module. It is ...'''
- `@hidden'
- 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.
- `@private'
- 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.
- `@reference'
- 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., Interesting Times, %% Victor Gollancz Ltd, 1994.''' ```%% @reference See Google for %% more information.'''
- `@see'
- See the `@see' function tag for details.
- `@since'
- 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.
- `@version'
- Specifies the module version. The content can be arbitrary text.
- `@deprecated'
- See the `@deprecated' module tag for details.
- `@doc'
- 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)
- `@equiv'
- 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'.
- `@hidden'
- 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.
- `@private'
- 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.
- `@see'
- 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. EDoc'". If no label text is specified, the reference itself is used as the label.
- `@since'
- Specifies in what version of the module the function was introduced; cf. the `@version' module tag. The content can be arbitrary text.
- `@spec'
- 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. 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 {@section Type specifications} for examples.
- `@throws'
- 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.
- `@type'
- See the `@type' generic tag 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.
| Reference syntax | Example | Scope |
|---|---|---|
| `Module' | {@link edoc_run}, `erl.lang.list' | Global |
| `Package.*' | `erl.lang.*' | Global |
| `Function/Arity' | `file/2' | Within module |
| `Module:Function/Arity' | {@link edoc:application/2} | Global |
| `Type()' | `filename()' | Within module |
| `Module:Type()' | {@link edoc:edoc_module()} | Global |
| `//Application' | {@link //edoc} | Global |
| `//Application/Module' | {@link //edoc/edoc_doclet} | Global |
| `//Application/Module:Function/Arity' | {@link //edoc/edoc_run:file/1} | Global |
| `//Application/Module:Type()' | {@link //edoc/edoc:edoc_module()} | Global |
- All elements must have explicit start and end tags, and be correctly nested. This means that you cannot e.g. write a `
- ' tag without also writing a corresponding ` ' 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.
- XHTML tag and attribute names should always be lower-case.
- Attributes must be quoted, as in e.g. `'.
', which has no actual content, you can write either the full `
', or better, use the XHTML abbreviated form `
'. 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 '%' 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 any %% XHTML markup. %% %% 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:
Paragraph splitting takes place after the actual XHTML parsing. It only affects block-level text, and not e.g., text within `This will all be part of the first paragraph. It can stretch over several lines and contain any XHTML markup.
This is the second paragraph. The above line is regarded as "empty" by EDoc, even though it ends with a space.
' markup, or text that is already within `' 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 ```
Concerning Hobbits
''' 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 ```Concerning Hobbits''' 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 "`http://www.w3c.org/'". 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 @todo tags for further details). === Verbatim quoting === In XHTML text, the '`' character (Unicode `000060', known as "grave accent" or "back-quote") can be used for verbatim quoting. This expansion takes place before XML parsing.
- A character sequence "
`...'" or "``...''" will be expanded to "`...'", where all occurrences of the special XML characters '`<'' and '`&'' (and for completeness, also '`>'') in the quoted text have been escaped to "`<'", "`&'", and "`>'", respectively. All whitespace is stripped from the beginning and end of the quoted text. Double back-quotes "``...''" can be used to quote text containing single '`` ' ''' characters. The automatic stripping of any surrounding whitespace makes it possible to write things like "`` 'foo@bar' ''". To quote text containing "''" verbatim, explicit `' markup or similar must be used. - A character sequence "
```...'''" will be expanded to "`'", 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. - To produce a single '
`'-character in XML without beginning a new quote, you can write "`'" (no space between the '`' and the '''). You can of course also use the XML character entity "``'".
%% @doc ...use the command ```erl -name foo''' to...
%% @doc ...as in the following code:
%% ```f(X) ->
%% case X of
%% ...
%% end'''
%% @doc ...or in the following:
%% ```
%% g(X) ->
%% fun () -> ... end
%% '''
== Macro expansion ==
Before the content of a tag is parsed, the text undergoes macro
expansion. The syntax for macro calls is:
@{@name}
or
@{@name argument}
where name and argument 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 "@{@" and
"`}'" delimiters must be balanced.
The argument text is first expanded in the current environment, and
the result is bound to the macro parameter, written
@{@?}. (If no argument is given, @{@?} 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 ===
@{@date}- Expands to the current date, as "Month Day Year", e.g. "{@date}".
@{@docRoot}- 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 `
' 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),
@{@docRoot}will always resolve to the empty string. @{@link reference. description}- This creates a hypertext link; cf. the
`@see' function tag above for
details. The description text (including the period separator)
is optional; if no text is given, the reference itself is
used. For example,
@{@link edoc:file/2}creates the link {@link edoc:file/2}, and `@{@link edoc:file/2. this link}' creates {@link edoc:file/2. this link}. @{@module}- Expands to the name of the current module. Only defined when a module is being processed.
@{@package}- Expands to the name of the current package.
@{@section heading}- Expands to a hypertext link to the specified section heading; see {@section Headings} for more information.
@{@time}- Expands to the current time, as "Hr:Min:Sec", e.g. "{@time}".
@{@type type-expression}- Formats a type expression within `
...' markup and with hypertext links for data types. For example,@{@type {options, List::edoc:option_list()@@}}generates "{@type {options, List::edoc:option_list()@}}". (Cf. {@section Escape sequences}.) @{@version}- Intended for use in `@version' tags. 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.
@{@" in the output, or use a
'`}'' character in the argument text of a macro call, the
following escape sequences may be used: @@{- Expands to "`{'". Example: ``` %% @doc A macro call starts with the sequence "@@@{@".'''
@@}- Expands to "`}'". Example: ``` %% @doc ...@{@foo ...{Key, Value@@}...}...'''
@@@@- Expands to "`@'". Example: ``` %% @doc Contact us at support@@@@@{@hostname}''' Will generate the text "Contact us at support@vaporware.acme.com" 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.'''
Spec |
::= | FunType "where"? DefList?
|
FunctionName |
::= | Atom |
FunType |
::= | "(" UnionTypes? ")" "->" UnionType |
UnionTypes |
::= | UnionType
|
UnionType |
::= | UnionList
|
Name |
::= | Variable |
UnionList |
::= | Type
|
Type |
::= | TypeVariable
|
Fields |
::= | Field
|
Field |
::= | Atom "=" UnionList |
BinType |
::= | "<<>>"
|
BaseType |
::= | "_" ":" Integer |
UnitType |
::= | "_" ":" "_" "*" Integer |
TypeVariable |
::= | Variable |
TypeName |
::= | Atom |
ModuleName |
::= | Atom
|
AppName |
::= | Atom |
DefList |
::= | Def
|
Def |
::= | TypeVariable "=" UnionList
|
TypeVariables |
::= | TypeVariable
|
Typedef |
::= | TypeName "(" TypeVariables? ")" DefList?
|
- `any()' means "any Erlang data type". `term()' is simply an alias for `any()'.
- `atom()', `binary()', `float()', `function()', `integer()', `pid()', `port()' and `reference()' are primitive data types of the Erlang programming language.
- `boolean()' is the subset of `atom()' consisting of the atoms `true' and `false'.
- `char()' is a subset of `integer()' representing character codes.
- `tuple()' is the set of all tuples `{...}'.
- `list(T)' is just an alias for `[T]'.
- `nil()' is an alias for the empty list `[]'.
- `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))'.
- `string()' is an alias for `[char()]'.
- `deep_string()' is recursively defined as `[char()+deep_string()]'.
- `none()' means "no data type". E.g., a function that never returns has type `(...) -> none()'