` markup, or text that is
already within `
` markup.

### Headings

Section headings, sub-headings, and sub-sub-headings, can be written using the
following notation:

```text
   == 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.,

```text
   == Concerning Hobbits ==
```

is equivalent to

```text
   
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.,

```text
   {@section Concerning Hobbits}
```

is equivalent to writing

```text
   Concerning Hobbits
```

The above expansions take place before XML parsing.

[](){: #External_links }

### External links

Writing a URL within brackets, as in "`[http://www.w3c.org/]`", will generate a
hyperlink such as [http://www.w3c.org/](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](chapter.md#gtag-todo) for further details).

[](){: #Verbatim_quoting }

### 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 "```".

Examples:

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

```erlang
%% @doc ...returns the atom `` 'foo@erlang.org' ''...
```

````erlang
%% @doc ...use the command ```erl -name foo''' to...
````

````erlang
%% @doc ...as in the following code:
%% ```f(X) ->
%%       case X of
%%          ...
%%       end'''
````

````erlang
%% @doc ...or in the following:
%% ```
%%     g(X) ->
%%       fun () -> ... end
%% '''
````

[](){: #Macro_expansion }

## Macro expansion

Before the content of a tag is parsed, the text undergoes _macro expansion_. The
syntax for macro calls is:

```text
    {@name}
```

or

```text
    {@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 }

### User-defined macros

Users can define their own macros by using the `def` EDoc option; see
`edoc:file/2` and `edoc:get_doc/2` for more information. User-defined macros
override predefined macros.

[](){: #Predefined_macros }

### Predefined macros

- **`{@date}`** - [](){: #predefmacro-date } Expands to the current date, as
  "`Month Day Year`", e.g. "Jan 29 2024".

- **`{@link reference. description}`** - [](){: #predefmacro-link } This creates
  a hypertext link; cf. the [@see function tag](chapter.md#ftag-see) 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 `edoc:file/2`, and
  `{@link edoc:file/2. this link}` creates [this link](`edoc:file/2`).

- **`{@module}`** - [](){: #predefmacro-module } Expands to the name of the
  current module. Only defined when a module is being processed.

- **`{@section heading}`** - [](){: #predefmacro-section } Expands to a
  hypertext link to the specified section heading; see
  [Headings](chapter.md#headings) for more information.

- **`{@time}`** - [](){: #predefmacro-time } Expands to the current time, as
  "`Hr:Min:Sec`", e.g. "14:53:19".

- **`{@type type-expression}`** - [](){: #predefmacro-type } Formats a type
  expression within `...` markup and with hypertext links for data
  types. For example, `{@type {options, List::edoc:option_list()@}}` generates
  "`{options, List::edoc:option_list()}`". (Cf.
  [Escape sequences](chapter.md#Escape_sequences).)

- **`{@version}`** - [](){: #predefmacro-version } Intended for use in
  [@version tags](chapter.md#mtag-version). 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.

[](){: #Escape_sequences }

### Escape sequences

To prevent certain characters from being interpreted as delimiters, for example
to produce the text "`{@`" 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:

  ```erlang
  %% @doc A macro call starts with the sequence "@{@".
  ```

- **`@}`** - Expands to "`}`". Example:

  ```erlang
  %% @doc ...{@foo ...{Key, Value@}...}...
  ```

- **`@@`** - Expands to "`@`". Example:

  ```erlang
  %% @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:

  ```erlang
  %% @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.
  ```

[](){: #Type_specifications }

## Type specifications

[](){: #Function_specifications }

### Function specifications

Note that although the syntax described in the following can still be used for
specifying functions we recommend that Erlang specifications (that is the
`-spec` and `-type` attributes) as described in
[Types and Function Specification](`e:system:typespec.md`) should be added to
the source code instead. This way the analyses of [Dialyzer](`m:dialyzer`)'s can
be utilized in the process of keeping the documentation consistent and
up-to-date.

Erlang specifications (`-spec` and `-type`) are required to properly generate
doc chunks. Redundant `-spec` attributes and `@spec` tags will cause warnings to
be emitted and the specifications to be skipped in chunks. Old-style `@spec` and
`@type` specifications can still be used to generate static HTML documentation.

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())`.

|                 |     |                                                                         |
| --------------- | --- | ----------------------------------------------------------------------- |
| `Spec`          | ::= | `FunType "where"? DefList?` \|                                          |
|                 |     | `FunctionName FunType "where"? DefList?`                                |
| `FunctionName`  | ::= | `Atom`                                                                  |
| `FunType`       | ::= | `"(" UnionTypes? ")" "->" UnionType`                                    |
| `UnionTypes`    | ::= | `UnionType` \| `UnionType "," UnionTypes`                               |
| `UnionType`     | ::= | `UnionList` \| `Name "::" UnionList`                                    |
| `Name`          | ::= | `Variable`                                                              |
| `UnionList`     | ::= | `Type` \| `Type "+" UnionList` \| `Type "\|" UnionList`                 |
| `Type`          | ::= | `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? ")"`          |
| `Fields`        | ::= | `Field` \| `Fields "," Fields`                                          |
| `Field`         | ::= | `Atom "=" UnionList`                                                    |
| `BinType`       | ::= | `"<<>>"` \|                                                             |
|                 |     | `"<<" BaseType ">>"` \|                                                 |
|                 |     | `"<<" UnitType ">>"` \|                                                 |
|                 |     | `"<<" BaseType "," UnitType ">>"`                                       |
| `BaseType`      | ::= | `"_" ":" Integer`                                                       |
| `UnitType`      | ::= | `"_" ":" "_" "*" Integer`                                               |
| `TypeVariable`  | ::= | `Variable`                                                              |
| `TypeName`      | ::= | `Atom`                                                                  |
| `ModuleName`    | ::= | `Atom` \| `ModuleName "." Atom`                                         |
| `AppName`       | ::= | `Atom`                                                                  |
| `DefList`       | ::= | `Def` \| `DefList Def` \| `DefList "," Def`                             |
| `Def`           | ::= | `TypeVariable "=" UnionList` \|                                         |
|                 |     | `TypeName "(" TypeVariables? ")" "=" UnionType`                         |
| `TypeVariables` | ::= | `TypeVariable` \|                                                       |
|                 |     | `TypeVariable "," TypeVariables`                                        |

_Table: specification syntax grammar_

Examples:

```erlang
-spec my_function(X :: integer()) -> integer().
%% @doc Creates ...
```

```erlang
%% @spec my_function(X::integer()) -> integer()
```

```erlang
%% @spec (X::integer()) -> integer()
```

```erlang
%% @spec sqrt(float()) -> float()
```

```erlang
%% @spec pair(S, T) -> {S, T}
```

```erlang
%% @spec append(List, List) -> List
%%       List = [term()]
```

```erlang
%% @spec append(A::List, B::List) -> List
%%       List = [Item]
%%       Item = term()
```

```erlang
%% @spec open(File::filename()) -> FileDescriptor
%% where
%%       filename() = string() + atom(),
%%       FileDescriptor = term()
```

```erlang
%% @spec close(graphics:window()) -> ok
```

The first example shows the recommended way of specifying functions.

In the above examples, `X`, `A`, `B`, and `File` are parameter names, used for
referring to the parameters from the documentation text. The _type variables_
`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 }

### Type definitions

Note that although the syntax described in the following can still be used for
specifying types we recommend that Erlang types as described in
[Types and Function Specification](`e:system:typespec.md`) should be added to
the source code instead.

Old-style `@type` tags will result in just type names, but no definitions, in
doc chunks - please use `-type` attributes to ensure all available type
information is available in the chunks. For static HTML, Erlang types will be
used unless there is a type alias with the same name.

The following grammar (see above for auxiliary definitions) describes the form
of the definitions that may follow a `@type` tag:

|           |     |                                                          |
| --------- | --- | -------------------------------------------------------- |
| `Typedef` | ::= | `TypeName "(" TypeVariables? ")" DefList?` \|            |
|           |     | `TypeName "(" TypeVariables? ")" "=" UnionList DefList?` |


_Table: type definition grammar_

(For a truly abstract data type, no equivalence is specified.) The main
definition may be followed by additional local definitions. Examples:

```erlang
-type my_list(X) :: [X]. %% A special kind of lists ...
```

```erlang
-opaque another_list(X) :: [X].
%% another_list() is a kind of list...
```

```erlang
%% @type myList(X). A special kind of lists ...
```

```erlang
%% @type filename() = string(). Atoms not allowed!
```

```erlang
%% @type thing(A) = {thong, A}
%%           A = term().
%%   A kind of wrapper type thingy.
```

The first two examples show the recommended way of specifying types.

[](){: #Pre-defined_data_types }

### Pre-defined data types

The following data types are predefined by EDoc, and may not be redefined:

```text
    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()
```

Details:

- `t:any/0` means "any Erlang data type". `t:term/0` is simply an alias for
  `t:any/0`.
- `t:atom/0`, `t:binary/0`, `t:float/0`, `t:function/0`, `t:integer/0`,
  `t:pid/0`, `t:port/0` and `t:reference/0` are primitive data types of the
  Erlang programming language.
- `t:boolean/0` is the subset of `t:atom/0` consisting of the atoms `true` and
  `false`.
- `t:char/0` is the subset of `t:integer/0` representing Unicode character
  codes: hex 000000-10FFFF.
- `t:tuple/0` is the set of all tuples `{...}`.
- [`list(T)`](`t:list/1`) is just an alias for `[T]`; list() is an alias for
  [`list(any())`](`t:list/1`), i.e., `[any()]`.
- `t:nil/0` 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))`.
- `t:string/0` is an alias for `[char()]`.
- `deep_string()` is recursively defined as `[char()+deep_string()]`.
- `t:none/0` means "no data type". E.g., a function that never returns has type
  `(...) -> none()`

[](){: #Doc_chunks }

## Doc chunks

EDoc implements
[EEP-48](https://www.erlang.org/erlang-enhancement-proposals/eep-0048.html) and
allows to output doc chunks for Erlang projects which use the EDoc language for
source code documentation.

There are two ways to generate the doc chunks: either by using
[bin/edoc](edoc_cmd.md) or by using the
[Rebar3 edoc command](http://rebar3.org/docs/commands/#edoc). Ultimately,
they're both just entry points to EDoc, the application, so deciding which to
use is just a matter of preference.

[](){: #Using_edoc_EScript }

### Using edoc EScript

In order to generate doc chunks using [bin/edoc](edoc_cmd.md), make sure the
compiled Erlang app can be found in the Erlang code path:

```text
$ pwd
/tmp/recon
$ rebar3 compile
$ export PATH="$(dirname `which erl`)/../lib/erlang/lib/edoc-0.12/bin:$PATH"
$ edoc -app recon -chunks -pa _build/default/lib/recon/ebin
Running with opts:
#{app => recon,
  code_paths => ["_build/default/lib/recon/ebin"],
  files => [],mode => chunks,run => app}
$ ls _build/default/lib/recon/doc/chunks/
recon.chunk        recon_lib.chunk    recon_rec.chunk
recon_alloc.chunk  recon_map.chunk    recon_trace.chunk
```

The project does not have to be built with Rebar3 - the above is just an
example. From now on the chunks will be available as the source of
[documentation for the Erlang shell](`m:shell_docs`):

```text
$ erl -pa _build/default/lib/recon/ebin
...
1> h(recon).

   recon

  Recon, as a module, provides access to the high-level functionality contained in the
  Recon application.
  ...

2> h(recon_alloc, allocators, 0).

  -spec allocators() -> [allocdata(term())].

  returns a dump of all allocator settings and values
```

[](){: #Using_Rebar3_edoc_command }

### Using Rebar3 edoc command

Doc chunks can also be built using `rebar3 edoc`, given `edoc_opts` is properly
set up:

```text
$ pwd
/tmp/recon
$ cat >> rebar.config < {edoc_opts, [{doclet, edoc_doclet_chunks},
>              {layout, edoc_layout_chunks},
>              {preprocess, true},
>              {dir, "_build/docs/lib/recon/doc"}]}.
> EOF
$ rebar3 edoc
$ ls _build/docs/lib/recon/doc/chunks/
recon.chunk        recon_lib.chunk    recon_rec.chunk
recon_alloc.chunk  recon_map.chunk    recon_trace.chunk
```

`rebar3 shell` will set up the paths for us if we use the `docs` profile:

```text
$ rebar3 as docs shell
...
1> h(recon).

   recon

  Recon, as a module, provides access to the high-level functionality contained in the
  Recon application.
  ...
```

[](){: #Using_the_EDoc_API }

### Using the EDoc API

EDoc comes with two sets of doclet/layout pairs:

- `m:edoc_doclet` and `m:edoc_layout` \- the default pair which is used to
  generate static HTML documentation
- `m:edoc_doclet_chunks` and `m:edoc_layout_chunks` \- the
  [EEP-48](https://www.erlang.org/erlang-enhancement-proposals/eep-0048.html)
  compliant pair which generates doc chunks with
  [erlang+html(3)](`e:edoc:doc_storage.md`)

In order to generate doc chunks using `edoc:application/2` or `edoc:files/2` we
have to specify which doclet and layout we want to use:

```erlang
Opts = [{doclet, edoc_doclet_chunks},
        {layout, edoc_layout_chunks}].
```

Then, it's just a matter of deciding whether we want to generate documentation
for the whole application (`edoc:application/2`) or only selected source files
(`edoc:files/2`):

```erlang
App = my_app.
edoc:application(App, Opts).
%% or
Files = ["src/my_app_mod1.erl", "src/my_app_mod2.erl"].
edoc:files(Files, Opts).
```

See `src/edoc_cli.erl` source code for an example of using this interface.

## 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.