Reference

Directives

The Erlang domain provides the following directives.

.. erl:module:: module_name

This directive marks the beginning of the description of a module.

This directive will also cause an entry in the global module index.

It has :platform:, :synopsis:, :deprecated: and :noindex options as same as py:module.

:platform: LIST

Comma separated list of the platforms

:synopsis: TEXT

One sentence description for the module’s purose.

:deprecated:

Mark a module as deprecated.

:noindex:

Prevent being shown in the general index.

See also

• py:module

• Basic Markup (:noindex: option)

.. erl:currentmodule:: module_name

Switch to the module without creating new module definition.

See also

• py:currentmodule

The following directives are provided for module level contents:

.. erl:function:: func_name(Arg1, Arg2, ...) -> Result

Describes a module-level function. Usage of this directive is almost as same as Python’s one.

Erlang domain can accept functions whose names are same. To identify these, Erlang have arity information.

Additionary, Erlang domain also accepts flavor name experimentally.

A function signature consists of followings:

• Module name followed by colon. (optional)

• Function name. (mandatory)

• Argument list ((Arg1, Arg2, ...)) or arity (/arity). (optional, but should write)

• Flavor name. (optional, experimental)

• when description. (optional)

• Return annoration (-> Result). (optional)

Example:

.. erl:module:: io

.. erl:function:: nl() -> ok

   Output newline.

.. erl:function:: put_chars(Chars) -> ok

   Output characters without formatting.

   :param Chars:  characters to be output.
   :type  Chars:  unicode:chardata()
   :rtype:  ``ok``

.. erl:function:: format(Fmt[, Args]) -> ok

   Output message with formatting, like ``printf`` in C.

   :param Fmt:   format string.
   :type  Fmt:   io:format()
   :param Args:  characters to be output.
   :type  Args:  [:erl:type:`term()`]
   :rtype:  ``ok``

.. erl:function:: format(Device, Fmt, Args) -> ok

   Output message into ``Device`` with formatting, like ``fprintf`` in C.

   :param Device:  output target.
   :type  Device:  io:device()
   :param Fmt:     format string.
   :type  Fmt:     io:format()
   :param Args:    characters to be output.
   :type  Args:    [:erl:type:`term()`]
   :rtype: ``ok``

These functions can be referenced by erl:func, for example:

* :erl:func:`io:nl/0`, :erl:func:`io:nl()`
* :erl:func:`io:put_chars/1`, :erl:func:`io:put_chars(Chars)`
* :erl:func:`io:format/1`
* :erl:func:`io:format/2`
* :erl:func:`io:format/3`

See also

• erl:func

• py:function

.. erl:type:: type_name(Arg1, Arg2, ...)

Describes a type.

A type signature consists of followings:

• Module name followed by colon. (optional)

• Type name. (mandatory)

• Argument list ((Arg1, Arg2, ...)) or arity (/arity). (optional, but should write)

• Flavor name. (optional, experimental)

• when description. (optional)

For example:

.. erl:module:: unicode

.. erl:type:: chardata()

.. erl:module:: orddict

.. erl:type:: orddict(Key, Value)

   :param Key:    type of the keys of the dict.
   :type  Key:    term()
   :param Value:  type of the values of the dict.
   :type  Value:  term()

Types can be referenced by erl:type, for example:

* :erl:type:`unicode:chardata/0`, :erl:type:`unicode:chardata()`
* :erl:type:`orddict:orddict/2`, :erl:type:`orddict:orddict(K, V)`

See also

• erl:type

.. erl:opaque:: opaque_type_name(Arg1, Arg2, ...)

Describes an opaque type.

The objects declared by this directive belong to the same namespace of the objects declared by erl:type directives.

Opaque type signatures take same format as a erl:type directive.

For example:

.. erl:module:: gb_trees

.. erl:opaque:: tree(Key, Value)

   :param Key:    type of the keys of the tree.
   :type  Key:    term()
   :param Value:  type of the values of the tree.
   :type  Value:  term()

Opaque types also can be referenced by erl:type, for example:

* :erl:type:`gb_trees:tree/2`, :erl:type:`gb_trees:tree(K, V)`

See also

• erl:type

.. erl:record:: #record_name{}

Describes a record.

Record signature consists of followings:

• Module name followed by colon. (optional)

• Record name. (mandatory)

• Record body ({ field description, ... }) or arity (/arity). (optional)

For example:

.. erl:module:: file

.. erl:record:: #file_info{}

   :param size:  size of the file.
   :type  size:  :type:`non_neg_integer()` | undefined
   :param type:  type of the file.
   :type  type:  ``device`` | ``directory`` | ``other`` | ``regular`` | ``symlink`` | ``undefined``

   ...

Records can be referenced by erl:record, for example:

* :erl:record:`file:#file_info{}`

See also

• erl:record

.. erl:macro:: ?MACRO_NAME(Arg1, Arg2, ...) -> Result

Describes a macro.

Macro signature consists of followings:

• Module name followed by colon. (optional)

• Macro name. (mandatory)

• Argument list ((Arg1, Arg2, ...)) or arity (/arity). (optional)

• Flavor name. (optional, experimental)

• when description. (optional)

• Return annoration (-> ...). (optional)

For example:

.. erl:module:: eunit

.. erl:macro:: ?TEST

   This macro is always defined (to true, unless previously defined
   by the user to have another value) whenever EUnit is enabled at
   compile time.

.. erl:macro:: ?assertEqual(Expect, Expr)

   Evaluates the expressions *Expect* and *Expr* and compares the
   results for equality, if testing is enabled. If the values are
   not equal, an informative exception will be generated.

   :param Expect:  an expected value.
   :type  Expect:  *A*
   :param Expr:    an actual value.
   :type  Expr:    *A*

Macros can be referenced by erl:macro, for example:

* :erl:macro:`eunit:?TEST`
* :erl:macro:`eunit:?assertEqual/2`

See also

• erl:macro

.. erl:callback:: callback_name(Arg1, Arg2, ...) -> Result

Describes a callback function.

Callbacks have an own namespace which is separated from erl:function.

Callback signature takes same format as erl:function.

For example:

.. erl:module:: gen_event

.. erl:callback:: handle_event(Event, State) -> Result

   Handles an event.

   :param Event:  the event.
   :type  Event:  term()
   :param State:  current state.
   :type  State:  term()
   :rtype:
     {``ok``, *NewState*} | {``ok``, *NewState*, ``hibernate``}
     | {``swap_handler``, *Args1*, *NewState*, *Handler2*, *Args2*} | ``remove_handler``

Callbacks can be referenced by erl:callback, for example:

* :erl:callback:`gen_event:handle_event/2`

See also

• erl:callback

Cross-referencing Erlang objects

The following roles refer to objects in modules and are possibly hyperlinked if a matching identifier is found:

:erl:mod:

Reference a module.

For example:

* :erl:mod:`lists`

:erl:func:

Reference an Erlang function.

Function reference signature has a same format as erl:function. when clause and a return annoration are not used for searching a target.

For example:

* :erl:func:`lists:append/1`
* :erl:func:`lists:append/2`

See also

• erl:function

:erl:type:

Reference a type or an opaque type.

Type reference signature has a same format as erl:type and erl:opaque. when clause is not used for searching a target.

For example:

* :erl:type:`unicode:chardata/0` (public type)
* :erl:type:`gb_trees:tree/2` (opaque type)

See also

• erl:type

• erl:opaque

:erl:record:

Reference a record. Actually, Erlang records have no namespaces. But Erlang domain handles with namespaces virtually.

Record reference signature has a same format as erl:record.

For example:

* :erl:record:`file:#file_info`

See also

• erl:record

:erl:macro:

Reference a macro.

Macro reference signature has a same format as erl:macro. when clause and a return annotation are not used for searching a target.

For example:

* :erl:macro:`eunit:?TEST`
* :erl:macro:`eunit:?assertEqual/2`

See also

• erl:macro

:erl:callback:

Reference a callback

Callback signature takes same format as erl:func.

For example:

* :erl:callback:`gen_event:handle_event/2`

See also

• erl:callback

Options and fields for module level directives

Available options:

:noindex:

Prevent being shown in the general index.

:deprecated:

Mark the object as deprecated.

:module: MODULE

Temporary change of a module to which the object belogs.

:flavor: FLAVOR

Experimantal feature. Same as Flavor name but not appeard in description text.

Example of options:

.. erl:function:: func(Flag :: abc) -> Result
   :noindex:
   :deprecated:
   :module: some_mod
   :flavor: abc

   process ``abc`` feature.

Available fields:

:param NAME:  DESC

Description of a parameter.

:type  NAME:  TYPE

Type of a parameter.

If the TYPE is plain text (no any markups), processed with erl:type.

:returns:  DESC

Description of the return value.

:rtype:  TYPE

Type of the return value.

If the TYPE is plain text (no any markups), processed with erl:type.

:raises NAME:  DESC

Description of an exception.

If there is no corresponding :raisetype NAME:, NAME is treated as EXC_TYPE. Could not use any markups in NAME.

If NAME contains space char, unexpected result is rendered.

:raisetype NAME:  EXC_TYPE

Type description for NAME.

If the EXC_TYPE is plain text (no any markups), processed as following:

• started with one of error class, error:, throw: or exit:, the error class is removed, output as plain text and continue to process rest part.

• if consists of alphabets or digits only (str.isalnum()), outputed as literal.

• otherwise, processed with erl:type.

Example of fields:

.. erl:function:: func(Flag :: abc) -> Result

   process ``abc`` feature.

   :param Flag:  A flag.
   :type  Flag:  ``abc``
   :returns:  A result.
   :rtype:    result()
   :raises badarg:  If the argument is bad.
   :raises throw:some_exc():  Some exception.

Following directives are met as module level directives:

• erl:function

• erl:type

• erl:opaque

• erl:record

• erl:macro

• erl:callback

Restriction on intersphinx target

When hyperlinking by intersphinx, link targets have written in either of followings

1. module:name

2. module:name/arity

3. module:name(Arg1, Arg2, ...)

Flavor name

Caution

This feature is implemented experimentally. This feature may be changed or removed in future release without notice.

Erlang domain can take an additional name in each objects. Flavor name is not a part of Erlang Language, introduced by Erlang domain itself to identify function clauses.

For example:

.. erl:function:: erlang:process_flag(Flag, Value) -> OldBoolean

.. erl:function:: erlang:process_flag(Flag :: trap_exit, Boolean) @trap_exit -> OldBoolean

.. erl:function:: erlang:process_flag(Flag :: error_handler, Module) @error_handler -> OldModule

.. erl:function:: erlang:process_flag(Flag :: min_heap_size, MinHeapSize) @min_heap_size -> OldMinHeapSize

* :erl:func:`erlang:process_flag/2`
* :erl:func:`erlang:process_flag/2@trap_exit`
* :erl:func:`erlang:process_flag/2@error_handler`
* :erl:func:`erlang:process_flag/2@min_heap_size`

These clauses are identified by the portion of @trap_exit or @error_handler, not by the erlang code Flag :: trap_exit.

It can be wrapped with brackets ([ and ]) to hide from document texts. e.g.:

.. erl:function:: erlang:process_flag(Flag :: trap_exit, Boolean) [@trap_exit] -> OldBoolean

* :erl:func:`erlang:process_flag/2[@trap_exit]`