# Module edoc

EDoc - the Erlang program documentation generator.

Copyright © 2001-2003 Richard Carlsson

- Description
- Data Types
- Function Index
- Function Details

Version: 0.6.1

Authors: Richard Carlsson (`richardc@csd.uu.se`) [web site: `http://www.csd.uu.se/~richardc/`].

## Description

EDoc - the Erlang program documentation generator.

This module provides the main user interface to EDoc.

- EDoc User Manual
- Running EDoc

## Data Types

### edoc_module()

abstract datatype: `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() = //kernel/file:filename()`

### option_list()

`option_list() = [term()]`

### package()

`package() = atom() | string()`

### syntaxTree()

`syntaxTree() = //syntax_tools/erl_syntax:syntaxTree()`

## Function Index

application/1 | Equivalent to `application(Application, [])`.
application/2 | Run EDoc on an application in its default app-directory.
application/3 | Run EDoc on an application located in the specified directory.
file/1 | Equivalent to `file(Name, [])`.
file/2 | Reads a source code file and outputs formatted documentation to a corresponding file.
files/1 | Equivalent to `packages(Packages, [])`.
files/2 | Runs EDoc on a given set of source files.
get_doc/1 | Equivalent to `get_doc(File, [])`.
get_doc/2 | Reads a source code file and extracts EDoc documentation data.
get_doc/3 | Like `get_doc/2`, but for a given environment parameter.
layout/1 | Equivalent to `layout(Doc, [])`.
layout/2 | Transforms EDoc module documentation data to text.
packages/1 | Equivalent to `packages(Packages, [])`.
packages/2 | Runs EDoc on a set of packages.
read/1 | Equivalent to `read(File, [])`.
read/2 | Reads and processes a source file and returns the resulting EDoc-text as a string.
read_comments/1 | Equivalent to `read_comments(File, [])`.
read_comments/2 | Extracts comments from an Erlang source code file.
read_source/1 | Equivalent to `read_source(File, [])`.
read_source/2 | Reads an Erlang source file and returns the list of "source code form" syntax trees.
run/3 | Runs EDoc on a given set of source files and/or packages.

## Function Details

### application/1

`application(Application::atom()) -> ok`

Equivalent to `application(Application, [])`.

### application/2

`application(Application::atom(), Options::option_list()) -> ok`

Run EDoc on an application in its default app-directory. See `application/3` for details.

See also: application/1.

### application/3

`application(Application::atom(), Dir::filename(), Options::option_list()) -> 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/3` for details.

See also: application/2.

### file/1

`file(Name::filename()) -> ok`

Equivalent to `file(Name, [])`.

This function is deprecated: See `file/2` for details.

### file/2

`file(Name::filename(), Options::option_list()) -> 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()}`
  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/1

`files(Files::[filename() | {package(), [filename()]}]) -> ok`

Equivalent to `packages(Packages, [])`.

### files/2

`files(Files::[filename() | {package(), [filename()]}], Options::option_list()) -> ok`

Equivalent to `run([], Files, Options)`.

Runs EDoc on a given set of source files. See `run/3` for details.

### get_doc/1

`get_doc(File::filename()) -> {ModuleName, edoc_module()}`

Equivalent to `get_doc(File, [])`.

### get_doc/2

`get_doc(File::filename(), Options::option_list()) -> {ModuleName, edoc_module()}`

- `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()}`
  Specifies a set of EDoc macro definitions. See Inline macro expansion for details.
`{hidden, bool()}`
  If the value is `true`, documentation of hidden functions will also be included. The default value is `false`.
`{private, bool()}`
  If the value is `true`, documentation of private functions will also be included. 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, edoc_extract:source/5.

### get_doc/3

`get_doc(File::filename(), Env::edoc_lib:edoc_env(), Options::option_list()) -> term()`

Like `get_doc/2`, but for a given environment parameter. `Env` is an environment created by `edoc_lib:get_doc_env/4`.

### layout/1

`layout(Doc::edoc_module()) -> string()`

Equivalent to `layout(Doc, [])`.

### layout/2

`layout(Doc::edoc_module(), Options::option_list()) -> 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.

### packages/1

`packages(Packages::[package()]) -> ok`

Equivalent to `packages(Packages, [])`.

### packages/2

`packages(Packages::[package()], Options::option_list()) -> ok`

Equivalent to `run(Packages, [], Options)`.

Runs EDoc on a set of packages. The `source_path` option is used to locate the files; see `run/3` for details. This function automatically appends the current directory to the source path.

### read/1

`read(File::filename()) -> string()`

Equivalent to `read(File, [])`.

### read/2

`read(File::filename(), Options::option_list()) -> 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/1

`read_comments(File) -> [comment()]`

Equivalent to `read_comments(File, [])`.

### read_comments/2

`read_comments(File::filename(), Options::option_list()) -> [comment()]`

- `comment() = {Line, Column, Indentation, Text}`
- `Line = integer()`
- `Column = integer()`
- `Indentation = integer()`
- `Text = [string()]`

Extracts comments from an Erlang source code file. See the module `//syntax_tools/erl_comment_scan` for details on the representation of comments. Currently, no options are avaliable.

### read_source/1

`read_source(Name::File) -> [syntaxTree()]`

Equivalent to `read_source(File, [])`.

### read_source/2

`read_source(File::filename(), Options::option_list()) -> [syntaxTree()]`

Reads an Erlang source file and returns the list of "source code form" syntax trees.

Options:

`{preprocess, bool()}`
  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. 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.

See also: //syntax_tools/erl_syntax, get_doc/2.

### run/3

`run(Packages::[package()], Files::[filename() | {package(), [filename()]}], Options::option_list()) -> ok`

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 `edoc:layout/2` for layout-related options, and `edoc: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.
`{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, bool()}`
  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, bool()}`
  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, bool()}`
  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.)

See also: application/2, files/2, packages/2.