table of contents
- stretch 1:19.2.1+dfsg-2+deb9u2
- testing 1:21.2.6+dfsg-1
- unstable 1:21.2.6+dfsg-1
- experimental 1:22.0.4+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() = file:filename():
- proplist() = [term()]:
- syntaxTree() = erl_syntax:syntaxTree():
EXPORTS¶
application(Application::atom()) -> okEquivalent 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:
- *
- 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(Name::filename()) -> ok
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 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::[filename()], Options::proplist())
-> ok
Runs EDoc on a given set of source files. See run/2 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:
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()}
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.
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::filename(),
Env::edoc_lib:edoc_env(), Options::proplist()) ->
{ModuleName, edoc_module()}
Types:
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::edoc_module(), Options::proplist())
-> string()
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(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:
- {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}.
See also: erl_syntax(3erl), get_doc/2.
run(Files::[filename()], Options::proplist())
-> ok
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 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.
- {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.
AUTHORS¶
Richard Carlsson <carlsson.richard@gmail.com>edoc 0.8.1 |