edoc(3erl)

edoc(3erl) — Erlang Module Definition 💖

bestie, this is the page for the edoc module, and the manual-name energy is right here near the top: edoc. We're documenting docs. It's meta like that. ✨

NAME

edoc — EDoc, the Erlang program documentation generator. 💅

DESCRIPTION

EDoc - the Erlang program documentation generator. 🌸

This module gives you the main user interface to EDoc. It's literally the front door. 🫶

• 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 document 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 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, 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 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, 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 substituted for macro calls is specified as either a string() or a function(). The function is called with the macro argument text, the current line number, and the current environment. 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: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, 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 module erl_comment_scan(3erl) for details on the representation of comments. Currently, no options are available. 💬

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 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}. 🚨
• {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(3erl), 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. 👀

Okay, options time — every single one, no skipping, because they all do something and you deserve the whole menu. 💖

• {app_default, string()} — sets the default base URI for applications that are still unknown. The "we don't know her yet" fallback, basically.
• {application, App::atom()} — says the documentation being generated describes the application App. This mainly affects generated references — so the refs know what's up.
• {dir, filename()} — the target directory where the generated documentation goes.
• {doc_path, [string()]} — 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, so you don't have to hand-add those.
• {doclet, Module::atom()} — the callback module used for creating the documentation. It 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()} — the suffix used for output files. Default is ".html". Heads up: this also affects generated references.
• {new, boolean()} — if true, any existing edoc-info file in the target directory is ignored and overwritten. Default is false.
• {source_path, [filename()]} — a list of file system paths used to locate the source code for packages.
• {source_suffix, string()} — the expected suffix of input files. Default is ".erl".
• {subpackages, boolean()} — if true, all subpackages of the specified packages are also included in the documentation. Default 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> — iconic, credited, periodt. 👑

---

That's the whole edoc 1.2 situation, bestie — straight from the edoc(3erl) manual page. Version and manual section secured; the footer didn't hand us a date, and we're not inventing one. 💅✨