edoc(3)

NAME
edoc - EDoc - the Erlang program documentation generator.

DESCRIPTION

This module provides the main user interface to EDoc.

    • EDoc User Manual

    • Running EDoc

DATA TYPES

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() :: #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).
env() :: #env{}.

    Environment information needed by EDoc for generating references.
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.
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(atom()) -> ok.

    Equivalent to application(Application, []).
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) -> 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(filename()) -> ok.

    Deprecated: See file/2 for details.

    Equivalent to file(Name, []).
file(Name, Options) -> ok when Name :: filename(), Options :: proplist().

    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.

    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, 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(filename()) -> {module(), edoc_module()}.

    Equivalent to get_doc(File, []).
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) -> 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(edoc_module()) -> string().

    Equivalent to layout(Doc, []).
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(filename()) -> string().

    Equivalent to read(File, []).
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(filename()) -> [comment()].

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

    Extracts comments from an Erlang source code file. See the module //syntax_tools/erl_comment_scan for details on the representation of comments. Currently, no options are available.
read_source(filename()) -> [syntaxTree()].

    Equivalent to read_source(File, []).
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) -> 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.