edoc — edoc v1.5

Search documentation of edoc

# edoc (edoc v1.5)

View Source

EDoc - the Erlang program documentation generator.

This module provides the main user interface to EDoc.

- EDoc User Manual
- Running EDoc

## Summary

### Types

comment/0
edoc_module/0

The EDoc documentation data for a module, expressed as an XML document in XMerL format. See the file `edoc.dtd` for details.

entry/0

Module Entries (one per function, plus module header and footer).

entry_data/0
env/0

Environment information needed by EDoc for generating references.

filename/0
function_name/0
module_meta/0

Module information.

ordset/1
proplist/0
syntaxTree/0
tag/0

Generic tag information. `#tag.form` is only defined if `#tag.origin` is `code`, that is the `#tag{}` represents a code fragment, not a doc comment tag.

### Functions

application(App)

Equivalent to application(Application, []).

application(App, Options)

Run EDoc on an application in its default app-directory. See `application/3` for details.

application(App, Dir, Options)

Run EDoc on an application located in the specified directory. Tries to automatically set up good defaults. Unless the user specifies otherwise

file(Name) deprecated

Equivalent to file(Name, []).

file(Name, Options) deprecated

Reads a source code file and outputs formatted documentation to a corresponding file.

files(Files)
files(Files, Options)

Equivalent to run(Files, Options).

get_doc(File)

Equivalent to get_doc(File, []).

get_doc(File, Options)

Reads a source code file and extracts EDoc documentation data. Note that without an environment parameter (see `get_doc/3`), hypertext links may not be correct.

get_doc(File, Env, Options)

Like `get_doc/2`, but for a given environment parameter. `Env` is an environment created by `edoc_lib:get_doc_env/3`.

layout(Doc)

Equivalent to layout(Doc, []).

layout(Doc, Opts)

Transforms EDoc module documentation data to text. The default layout creates an HTML document.

read(File)

Equivalent to read(File, []).

read(File, Opts)

Reads and processes a source file and returns the resulting EDoc-text as a string. See `get_doc/2` and `layout/2` for options.

read_comments(File)

Equivalent to read_comments(File, []).

read_comments(File, Opts)

Extracts comments from an Erlang source code file. See the module `erl_comment_scan` for details on the representation of comments. Currently, no options are available.

read_source(Name)

Equivalent to read_source(File, []).

read_source(File, Opts)

Reads an Erlang source file and returns the list of "source code form" syntax trees.

run(Files, Opts)

Runs EDoc on a given set of source files. Note that the doclet plugin module has its own particular options; see the `doclet` option below.

## Types

# comment/0

    -type comment() :: erl_comment_scan:comment().

# edoc_module/0

    -type edoc_module() :: xmerl_scan:xmlElement().

The EDoc documentation data for a module, expressed as an XML document in XMerL format. See the file `edoc.dtd` for details.

# entry/0

    -type entry() ::
              #entry{name :: function_name() | atom(),
                     args :: [atom() | list()],
                     line :: integer(),
                     export :: boolean(),
                     data :: entry_data()}.

Module Entries (one per function, plus module header and footer).

# entry_data/0

    -type entry_data() :: term().

# env/0

    -type env() ::
              #env{module :: term(),
                   root :: term(),
                   file_suffix :: term(),
                   apps :: term(),
                   modules :: term(),
                   app_default :: term(),
                   macros :: term(),
                   includes :: term()}.

Environment information needed by EDoc for generating references.

# filename/0

    -type filename() :: file:filename().

# function_name/0

    -type function_name() :: {atom(), integer()}.

# module_meta/0

    -type module_meta() ::
              #module{name :: [] | atom(),
                      parameters :: none | [atom()],
                      functions :: ordset(function_name()),
                      exports :: ordset(function_name()),
                      attributes :: ordset({atom(), term()}),
                      records :: [{atom(), [{atom(), term()}]}],
                      encoding :: epp:source_encoding(),
                      file :: file:filename()}.

Module information.

# ordset/1

    -type ordset(T) :: ordsets:ordset(T).

# proplist/0

    -type proplist() :: proplists:proplist().

# syntaxTree/0

    -type syntaxTree() :: erl_syntax:syntaxTree().

# tag/0

    -type tag() ::
              #tag{name :: atom(),
                   line :: integer(),
                   origin :: comment | code,
                   data :: term(),
                   form :: undefined | erl_parse:abstract_form()}.

Generic tag information. `#tag.form` is only defined if `#tag.origin` is `code`, that is the `#tag{}` represents a code fragment, not a doc comment tag.

## Functions

# application(App)

    -spec application(atom()) -> ok.

Equivalent to application(Application, []).

# application(App, Options)

    -spec application(App, Options) -> ok when App :: atom(), Options :: proplist().

Run EDoc on an application in its default app-directory. See `application/3` for details.

See also: application/1.

# application(App, Dir, Options)

    -spec application(App, Dir, Options) -> ok when App :: atom(), Dir :: filename(), Options :: proplist().

Run EDoc on an application located in the specified directory. Tries to automatically set up good defaults. Unless the user specifies otherwise:

- The `doc` subdirectory will be used as the target directory, if it exists; otherwise the application directory is used.
- The source code is assumed to be located in the `src` subdirectory, if it exists, or otherwise in the application directory itself.
- The `subpackages` option is turned on. All found source files will be processed.
- The `include` subdirectory is automatically added to the include path. (Only important if preprocessing is turned on.)

See `run/2` for details, including options.

See also: application/2.

# file(Name)

This function is deprecated. See file/2 for details..

    -spec file(filename()) -> ok.

Equivalent to file(Name, []).

# file(Name, Options)

This function is deprecated. This is part of the old interface to EDoc and is mainly kept for backwards compatibility. The preferred way of generating documentation is through one of the functions application/2 and files/2..

    -spec file(Name, Options) -> ok when Name :: filename(), Options :: proplist().

Reads a source code file and outputs formatted documentation to a corresponding file.

Options:

`{dir, filename()}`
  Specifies the output directory for the created file. (By default, the output is written to the directory of the source file.)
`{source_suffix, string()}`
  Specifies the expected suffix of the input file. The default value is `".erl"`.
`{file_suffix, string()}`
  Specifies the suffix for the created file. The default value is `".html"`.

See `get_doc/2` and `layout/2` for further options.

For running EDoc from a Makefile or similar, see `edoc_run:file/1`.

See also: read/2.

# files(Files)

    -spec files([filename()]) -> ok.

# files(Files, Options)

    -spec files(Files, Options) -> ok when Files :: [filename()], Options :: proplist().

Equivalent to run(Files, Options).

Runs EDoc on a given set of source files. See `run/2` for details, including options.

# get_doc(File)

    -spec get_doc(filename()) -> {module(), edoc_module()}.

Equivalent to get_doc(File, []).

# get_doc(File, Options)

    -spec get_doc(File, Options) -> R
                     when
                         File :: filename(),
                         Options :: proplist(),
                         R :: {module(), edoc_module()} | {module(), edoc_module(), [entry()]}.

Reads a source code file and extracts EDoc documentation data. Note that without an environment parameter (see `get_doc/3`), hypertext links may not be correct.

Options:

`{def, Macros}`
  - `Macros` = `Macro | [Macro]`
  - `Macro` = `{Name::atom(), Text::string() | MacroFun}`
  - `MacroFun` = `fun((MacroArgument::string(), Line :: integer(), edoc_lib:edoc_env()) -> (Text::string()))`
  Specifies a set of user-defined EDoc macros. The text substituted for macro calls is specified as either a `string()` or a `function()`. The function is called with the macro argument text, the current line number, and the current environment. The fun is to return a `string()`. See Macro expansion for details.
`{hidden, boolean()}`
  If the value is `true`, documentation of hidden functions will also be included. The default value is `false`.
`{private, boolean()}`
  If the value is `true`, documentation of private functions will also be included. The default value is `false`.
`{todo, boolean()}`
  If the value is `true`, To-Do notes written using `@todo` or `@TODO` tags will be included in the documentation. The default value is `false`.

See `read_source/2`, `read_comments/2` and `edoc_lib:get_doc_env/3` for further options.

See also: get_doc/3, layout/2, read/2, run/2, edoc_extract:source/5.

# get_doc(File, Env, Options)

    -spec get_doc(File, Env, Options) -> R
                     when
                         File :: filename(),
                         Env :: env(),
                         Options :: proplist(),
                         R :: {module(), edoc_module()} | {module(), edoc_module(), [entry()]}.

Like `get_doc/2`, but for a given environment parameter. `Env` is an environment created by `edoc_lib:get_doc_env/3`.

# layout(Doc)

    -spec layout(edoc_module()) -> string().

Equivalent to layout(Doc, []).

# layout(Doc, Opts)

    -spec layout(Doc, Opts) -> term() when Doc :: edoc_module(), Opts :: proplist().

Transforms EDoc module documentation data to text. The default layout creates an HTML document.

Options:

`{layout, Module::atom()}`
  Specifies a callback module to be used for formatting. The module must export a function `module(Doc, Options)`. The default callback module is `edoc_layout`; see `edoc_layout:module/2` for layout-specific options.

See also: file/2, layout/1, read/2, run/2.

# read(File)

    -spec read(filename()) -> string().

Equivalent to read(File, []).

# read(File, Opts)

    -spec read(File, Opts) -> string() when File :: filename(), Opts :: proplist().

Reads and processes a source file and returns the resulting EDoc-text as a string. See `get_doc/2` and `layout/2` for options.

See also: file/2.

# read_comments(File)

    -spec read_comments(filename()) -> [comment()].

Equivalent to read_comments(File, []).

# read_comments(File, Opts)

    -spec read_comments(File, Opts) -> [comment()] when File :: filename(), Opts :: proplist().

Extracts comments from an Erlang source code file. See the module `erl_comment_scan` for details on the representation of comments. Currently, no options are available.

# read_source(Name)

    -spec read_source(filename()) -> [syntaxTree()].

Equivalent to read_source(File, []).

# read_source(File, Opts)

    -spec read_source(File, Opts) -> [syntaxTree()] when File :: filename(), Opts :: proplist().

Reads an Erlang source file and returns the list of "source code form" syntax trees.

Options:

`{preprocess, boolean()}`

  If the value is `true`, the source file will be read via the Erlang preprocessor (`epp`). The default value is `false`. `no_preprocess` is an alias for `{preprocess, false}`.

  Normally, preprocessing is not necessary for EDoc to work, but if a file contains too exotic definitions or uses of macros, it will not be possible to read it without preprocessing. Note: comments in included files will not be available to EDoc, even with this option enabled.
`{includes, Path::[string()]}`
  Specifies a list of directory names to be searched for include files, if the `preprocess` option is turned on. Also used with the `@headerfile` tag. The default value is the empty list. The directory of the source file is always automatically appended to the search path.
`{macros, [{atom(), term()}]}`
  Specifies a list of pre-defined Erlang preprocessor (`epp`) macro definitions, used if the `preprocess` option is turned on. The default value is the empty list.
`{report_missing_types, boolean()}`
  If the value is `true`, warnings are issued for missing types. The default value is `false`. `no_report_missing_types` is an alias for `{report_missing_types, false}`.
`{link_predefined_types, boolean()}`
  If the value is `true`, all predefined data types will have a link to the erlang module. This option is to be used when generating documentation for the Erlang/OTP docs. The default value is `false`. `no_link_predefined_types` is an alias for `{link_predefined_types, false}`.

See also: //syntax_tools/erl_syntax, get_doc/2.

# run(Files, Opts)

    -spec run(Files, Opts) -> ok when Files :: [filename()], Opts :: proplist().

Runs EDoc on a given set of source files. Note that the doclet plugin module has its own particular options; see the `doclet` option below.

Also see `layout/2` for layout-related options, and `get_doc/2` for options related to reading source files.

Options:

`{app_default, string()}`
  Specifies the default base URI for unknown applications.
`{application, App::atom()}`
  Specifies that the generated documentation describes the application `App`. This mainly affects generated references.
`{dir, filename()}`
  Specifies the target directory for the generated documentation.
`{doc_path, [string()]}`
  Specifies a list of file system paths pointing to directories that contain EDoc-generated documentation. All paths for applications in the code path are automatically added.
`{doclet, Module::atom()}`
  Specifies a callback module to be used for creating the documentation. The module must export a function `run(Cmd, Ctxt)`. The default doclet module is `edoc_doclet`; see `edoc_doclet:run/2` for doclet-specific options.
`{file_suffix, string()}`
  Specifies the suffix used for output files. The default value is `".html"`. Note that this also affects generated references.
`{new, boolean()}`
  If the value is `true`, any existing `edoc-info` file in the target directory will be ignored and overwritten. The default value is `false`.
`{source_path, [filename()]}`
  Specifies a list of file system paths used to locate the source code for packages.
`{source_suffix, string()}`
  Specifies the expected suffix of input files. The default value is `".erl"`.
`{subpackages, boolean()}`

  If the value is `true`, all subpackages of specified packages will also be included in the documentation. The default value is `false`. `no_subpackages` is an alias for `{subpackages, false}`.

  Subpackage source files are found by recursively searching for source code files in subdirectories of the known source code root directories. (Also see the `source_path` option.) Directory names must begin with a lowercase letter and contain only alphanumeric characters and underscore, or they will be ignored. (For example, a subdirectory named `test-files` will not be searched.)

See also: application/2, files/2.