edoc - the Erlang program documentation generator.
Please see following description for synopsis
edoc(3) Erlang Module Definition edoc(3)
NAME
edoc - EDoc - the Erlang program documentation generator.
DESCRIPTION
EDoc - the Erlang program documentation generator.
This module provides the main user interface to EDoc.
* EDoc User Manual
* Running EDoc
DATA TYPES
comment() = erl_comment_scan:comment():
edoc_module() = xmerl_scan:xmlElement():
The EDoc documentation data for a module, expressed as an XML docu-
ment 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).
entry_data() = term():
env() = #env{}:
Environment information needed by EDoc for generating references.
filename() = file:filename():
function_name() = {atom(), integer()}:
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(T) = ordsets:ordset(T):
proplist() = proplists:proplist():
syntaxTree() = erl_syntax:syntaxTree():
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.
EXPORTS
application(App::atom()) -> ok
Equivalent to application(Application, []).
application(App, Options) -> ok
Types:
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
Types:
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 subdi-
rectory, 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::filename()) -> ok
This function is deprecated: See file/2 for details.
Equivalent to file(Name, []).
file(Name, Options) -> ok
Types:
Name = filename()
Options = proplist()
This function is deprecated: This is part of the old interface
to EDoc and is mainly kept for backwards compatibility. The pre-
ferred 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::[filename()]) -> ok
files(Files, Options) -> ok
Types:
Files = [filename()]
Options = proplist()
Runs EDoc on a given set of source files. See run/2 for details,
including options.
get_doc(File::filename()) -> {module(), edoc_module()}
Equivalent to get_doc(File, []).
get_doc(File, Options) -> R
Types:
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 sub-
stituted for macro calls is specified as either a string()
or a function(). The function is called with the macro argu-
ment text, the current line number, and the current environ-
ment. 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
Types:
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::edoc_module()) -> string()
Equivalent to layout(Doc, []).
layout(Doc, Opts) -> string()
Types:
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:mod-
ule/2 for layout-specific options.
See also: file/2, layout/1, read/2, run/2.
read(File::filename()) -> string()
Equivalent to read(File, []).
read(File, Opts) -> string()
Types:
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::filename()) -> [comment()]
Equivalent to read_comments(File, []).
read_comments(File, Opts) -> [comment()]
Types:
File = filename()
Opts = proplist()
Extracts comments from an Erlang source code file. See the mod-
ule erl_comment_scan(3) for details on the representation of
comments. Currently, no options are avaliable.
read_source(Name::filename()) -> [syntaxTree()]
Equivalent to read_source(File, []).
read_source(File, Opts) -> [syntaxTree()]
Types:
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 prepro-
cessing. Note: comments in included files will not be avail-
able 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 auto-
matically 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: erl_syntax(3), get_doc/2.
run(Files, Opts) -> ok
Types:
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 documenta-
tion.
{doc_path, [string()]}:
Specifies a list of file system paths pointing to directo-
ries 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 doc-
umentation. 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 ref-
erences.
{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 con-
tain 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.
AUTHORS
Richard Carlsson <carlsson.richard@gmail.com>
edoc 1.1 edoc(3)