table of contents
other versions
- jessie 1:17.3-dfsg-4+deb8u2
- jessie-backports 1:19.2.1+dfsg-2+deb9u1~bpo8+1
- stretch 1:19.2.1+dfsg-2+deb9u2
- testing 1:21.2.5+dfsg-1
- unstable 1:21.2.6+dfsg-1
- experimental 1:22.0~rc1+dfsg-1
edoc(3erl) | Erlang Module Definition | edoc(3erl) |
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() = {Line, Column, Indentation, Text}:
- *
- Line = integer()
- *
- Column = integer()
- *
- Indentation = integer()
- *
- Text = [string()]
- edoc_module():
The EDoc documentation data for a module, expressed as an XML document in
XMerL format. See the file edoc.dtd for details.
- filename() = filename() (see module //kernel/file):
- package() = atom() | string():
- proplist() = [term()]:
- syntaxTree() = syntaxTree() (see module //syntax_tools/erl_syntax):
EXPORTS¶
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:
See run/3 for details, including options.
See also: application/2.
file(Name::filename()) -> ok
- *
- 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.)
This function is deprecated: See file/2 for details.
Equivalent to file(Name, []).
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:
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
- {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".
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:
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.
get_doc(File::filename(), Env::edoc_env() (see module edoc_lib),
Options::proplist()) -> {ModuleName, edoc_module()}
- {def, Macros}:
- *
- Macros = Macro | [Macro]
- *
- Macro = {Name::atom(), Text::string()}
Specifies a set of EDoc macro definitions. See Inline 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.
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:
See also: file/2, layout/1, read/2,
run/3.
packages(Packages::[package()]) -> ok
- {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.
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()]
Extracts comments from an Erlang source code file. See the module
erl_comment_scan(3erl) 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:
{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}.
See also: erl_syntax(3erl), get_doc/2.
run(Packages::[package()], Files::[filename() | {package(), [filename()]}],
Options::proplist()) -> ok
- {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.
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:
See also: application/2, files/2, packages/2.
- {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 URI:s pointing to directories that contain EDoc-generated documentation. URI without a 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()}:
- 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.
- {exclude_packages, [package()]}:
- Lists packages to be excluded from the documentation. Typically used in conjunction with the subpackages option.
- {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.
- {packages, boolean()}:
- If the value is 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.
If the source code is organized in a hierarchy of subdirectories although it
does not use packages, use no_packages together with the
recursive-search subpackages option (on by default) to automatically
generate documentation for all the modules.
- {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}. See also the exclude_packages option.
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.)
AUTHORS¶
Richard Carlsson <carlsson.richard@gmail.com>edoc 0.7.15 |