View Source edoc (edoc v1.3)
EDoc - the Erlang program documentation generator.
This module provides the main user interface to EDoc.
Summary
Types
The EDoc documentation data for a module, expressed as an XML document in XMerL format. See the file edoc.dtd
for details.
Module Entries (one per function, plus module header and footer).
Environment information needed by EDoc for generating references.
Module information.
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
Equivalent to application(Application, []).
Run EDoc on an application in its default app-directory. See application/3
for details.
Run EDoc on an application located in the specified directory. Tries to automatically set up good defaults. Unless the user specifies otherwise
Equivalent to file(Name, []).
Reads a source code file and outputs formatted documentation to a corresponding file.
Equivalent to run([], Files, Options).
Equivalent to get_doc(File, []).
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.
Like get_doc/2
, but for a given environment parameter. Env
is an environment created by edoc_lib:get_doc_env/3
.
Equivalent to layout(Doc, []).
Transforms EDoc module documentation data to text. The default layout creates an HTML document.
Equivalent to read(File, []).
Equivalent to read_comments(File, []).
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.
Equivalent to read_source(File, []).
Reads an Erlang source file and returns the list of "source code form" syntax trees.
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
-type comment() :: erl_comment_scan:comment().
-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.
-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).
-type entry_data() :: term().
-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.
-type filename() :: file:filename().
-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.
-type ordset(T) :: ordsets:ordset(T).
-type proplist() :: proplists:proplist().
-type syntaxTree() :: erl_syntax:syntaxTree().
-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
-spec application(atom()) -> ok.
Equivalent to application(Application, []).
Run EDoc on an application in its default app-directory. See application/3
for details.
See also: application/1.
-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.
-spec file(filename()) -> ok.
Equivalent to file(Name, []).
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.
-spec files([filename()]) -> ok.
Equivalent to run([], Files, Options).
Runs EDoc on a given set of source files. See run/2
for details, including options.
-spec get_doc(filename()) -> {module(), edoc_module()}.
Equivalent to get_doc(File, []).
-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()))
string()
or afunction()
. The function is called with the macro argument text, the current line number, and the current environment. The fun is to return astring()
. See Macro expansion for details.{hidden, boolean()}
- If the value is
true
, documentation of hidden functions will also be included. The default value isfalse
. {private, boolean()}
- If the value is
true
, documentation of private functions will also be included. The default value isfalse
. {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 isfalse
.
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.
-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
.
-spec layout(edoc_module()) -> string().
Equivalent to layout(Doc, []).
-spec layout(Doc, Opts) -> string() 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 isedoc_layout
; seeedoc_layout:module/2
for layout-specific options.
Equivalent to read(File, []).
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.
Equivalent to read_comments(File, []).
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.
-spec read_source(filename()) -> [syntaxTree()].
Equivalent to read_source(File, []).
-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
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.true
, the source file will be read via the Erlang preprocessor (epp
). The default value isfalse
.no_preprocess
is an alias for{preprocess, false}
.{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 thepreprocess
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 isfalse
.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 isfalse
.no_link_predefined_types
is an alias for{link_predefined_types, false}
.
See also: //syntax_tools/erl_syntax, get_doc/2.
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 isedoc_doclet
; seeedoc_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 existingedoc-info
file in the target directory will be ignored and overwritten. The default value isfalse
. {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
Subpackage source files are found by recursively searching for source code files in subdirectories of the known source code root directories. (Also see thetrue
, all subpackages of specified packages will also be included in the documentation. The default value isfalse
.no_subpackages
is an alias for{subpackages, false}
.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 namedtest-files
will not be searched.)
See also: application/2, files/2.