EDoc - the Erlang program documentation generator.
This module provides the main user interface to EDoc.
edoc_module()
filename() = filename() (see module //kernel/file)
package() = atom() | string()
proplist() = [term()]
syntaxTree() = syntaxTree() (see module //syntax_tools/erl_syntax)
application(Application::atom()) -> ok
Equivalent to application(Application, []).
application(Application::atom(), Options::proplist()) -> ok
Run EDoc on an application in its default app-directory. See application/3 for details.
See also: application/1.
application(Application::atom(), Dir::filename(), Options::proplist()) -> ok
Run EDoc on an application located in the specified directory. Tries to automatically set up good defaults. Unless the user specifies otherwise:
doc
subdirectory will be used as the target directory, if
it exists; otherwise the application directory is used.
src
subdirectory, if it exists, or otherwise in the application
directory itself.
include
subdirectory is automatically added to the
include path. (Only important if preprocessing is turned on.)
See run/3 for details, including options.
See also: application/2.
file(Name::filename(), Options::proplist()) -> ok
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, packages/2 and files/2.
Reads a source code file and outputs formatted documentation to a corresponding file.
Options:
{dir, filename()}
{source_suffix, string()}
".erl"
.
{file_suffix, string()}
".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() | {package(), [filename()]}]) -> ok
Equivalent to packages(Packages, []).
files(Files::[filename() | {package(), [filename()]}], Options::proplist()) -> ok
Runs EDoc on a given set of source files. See run/3 for details, including options.
get_doc(File::filename()) -> {ModuleName, edoc_module()}
Equivalent to get_doc(File, []).
get_doc(File::filename(), Options::proplist()) -> {ModuleName, edoc_module()}
Types:
ModuleName = atom()
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()}
{hidden, bool()}
true
, documentation of hidden functions will
also be included. The default value is false
.
{private, bool()}
true
, documentation of private functions will
also be included. The default value is false
.
{todo, bool()}
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/4 for further options.
See also: get_doc/3, layout/2, read/2, run/3, edoc_extract:source/5.
Types:
ModuleName = atom()
Like get_doc/2, but for a given environment
parameter. Env
is an environment created by edoc_lib:get_doc_env/4.
layout(Doc::edoc_module()) -> string()
Equivalent to layout(Doc, []).
layout(Doc::edoc_module(), Options::proplist()) -> string()
Transforms EDoc module documentation data to text. The default layout creates an HTML document.
Options:
{layout, Module::atom()}
module(Doc, Options)
. The
default callback module is edoc_layout; see edoc_layout:module/2 for layout-specific options.
packages(Packages::[package()]) -> ok
Equivalent to packages(Packages, []).
packages(Packages::[package()], Options::proplist()) -> ok
Runs EDoc on a set of packages. The source_path
option is used
to locate the files; see run/3 for details, including
options. This function automatically appends the current directory to
the source path.
read(File::filename()) -> string()
Equivalent to read(File, []).
read(File::filename(), Options::proplist()) -> string()
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) -> [comment()]
Equivalent to read_comments(File, []).
read_comments(File::filename(), Options::proplist()) -> [comment()]
Types:
{Line, Column, Indentation, Text}
Line = integer()
Column = integer()
Indentation = integer()
Text = [string()]
Extracts comments from an Erlang source code file. See the module erl_comment_scan(3) for details on the representation of comments. Currently, no options are avaliable.
read_source(Name::File) -> [syntaxTree()]
Equivalent to read_source(File, []).
read_source(File::filename(), Options::proplist()) -> [syntaxTree()]
Reads an Erlang source file and returns the list of "source code form" syntax trees.
Options:
{preprocess, bool()}
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}
.{includes, Path::[string()]}
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()}]}
epp
)
macro definitions, used if the preprocess
option is turned on.
The default value is the empty list.
See also: erl_syntax(3), get_doc/2.
Runs EDoc on a given set of source files and/or packages. 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()}
{application, App::atom()}
App
. This mainly affects generated references.
{dir, filename()}
{doc_path, [string()]}
scheme://
part are
taken as relative to file://
. (Note that such paths must use
/
as separator, regardless of the host operating system.)
{doclet, Module::atom()}
run(Cmd, Ctxt)
.
The default doclet module is edoc_doclet; see edoc_doclet:run/2 for doclet-specific options.
{exclude_packages, [package()]}
subpackages
option.
{file_suffix, string()}
".html"
. Note that this also affects generated references.
{new, bool()}
true
, any existing edoc-info
file in the
target directory will be ignored and overwritten. The default
value is false
.
{packages, bool()}
true
, it it assumed that packages (module
namespaces) are being used, and that the source code directory
structure reflects this. The default value is true
. (Usually,
this does the right thing even if all the modules belong to the
top-level "empty" package.) no_packages
is an alias for
{packages, false}
. See the subpackages
option below for
further details.no_packages
together with the recursive-search subpackages
option (on by default) to automatically generate documentation
for all the modules.
{source_path, [filename()]}
{source_suffix, string()}
".erl"
.
{subpackages, bool()}
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}
. See also the exclude_packages
option.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, packages/2.