---
name: "edoc"
section: "3erl"
platform: "linux"
package: "erlang-manpages"
version: "1:25.2.3+dfsg-1+deb12u4"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/edoc/3erl"
---

# edoc(3erl)

EDoc - the Erlang program documentation generator.

## 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 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)](/erl_comment_scan/3erl.md) 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)](/erl_syntax/3erl.md), 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 documentation.

- ***{doc\_path, \[string()\]}*:**

  Specifies 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.

- ***{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\>*