Module edoc

EDoc - the Erlang program documentation generator.

Copyright © 2001-2003 Richard Carlsson

Version: 0.4 beta

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.

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()]

Function Index

application/1

Equivalent to application(Application, []).

application/2Run EDoc on an application in its default app-directory.
application/3Run EDoc on an application located in the specified directory.
file/1

Equivalent to file(Name, []).

file/2Reads a source code file and outputs formatted documentation to a corresponding file.
files/1

Equivalent to packages(Packages, []).

files/2Run EDoc on a given set of source files.
get_doc/1

Equivalent to get_doc(File, []).

get_doc/2Reads a source code file and extracts EDoc documentation data.
get_doc/3Like get_doc/2, but for a given environment parameter.
layout/1

Equivalent to layout(Doc, []).

layout/2Transforms EDoc documentation data to text.
packages/1

Equivalent to packages(Packages, []).

packages/2Run EDoc on a set of packages.
read/1

Equivalent to read(File, []).

read/2Like file/2, but returns the resulting text directly instead of writing to a file.
read_comments/1

Equivalent to read_comments(File, []).

read_comments/2Extracts comments from an Erlang source code file.
read_source/1

Equivalent to read_source(File, []).

read_source/2Reads an Erlang source file and returns the list of "source code form" syntax trees.
run/3Run 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 also: application/1, application/3, run/3.

application/3

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

Run EDoc on an application located in the specified directory.

See also: application/2, run/3.

file/1

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

Equivalent to file(Name, []).

file/2

file(Name::filename(), Options::option_list()) -> ok

Reads a source code file and outputs formatted documentation to a corresponding file.

Note: This function is 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/1, packages/2 and files/2.

Possible options are:

{def, Macros}
Specifies a set of macro definitions; see get_doc/2 for details.
{dir, filename()}
Specifies the output directory for the created file. (By default, the output is written to the directory of the source file.)
{file_suffix, string()}
Specifies the suffix for the created file. The default value is ".html".
{layout, atom()}
Specifies a callback module to be used for formatting the internal XML representation as text. See layout/2 for details.
{preprocess, bool()}
If the value is true, the source file will be read via the Erlang preprocessor (epp). The default value is 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.
{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 get_doc/2 for further options.

For running EDoc from a Makefile or similar, see edoc_run:file/1.

See also: //stdlib/epp, get_doc/2, layout/2, 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).

Run EDoc on a given set of source files.

See also: run/3.

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()}

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}
where Specifies a set of macro definitions. See Inline macro expansion for details.

See file/2 for options pertaining to reading source code files.

See also: //xmerl, file/2, get_doc/3, layout/2, read_comments/2, read_source/2, edoc_extract:source/4.

get_doc/3

get_doc(File::filename(), Env::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 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 also: get_doc/2, edoc_layout:module/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).

Run EDoc on a set of packages. The source-path will be used to find the files.

See also: run/3.

read/1

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

Equivalent to read(File, []).

read/2

read(File::filename(), Options::option_list()) -> string()

Like file/2, but returns the resulting text directly instead of writing to a file. See file/2 for options pertaining to reading source code files.

See also: file/2, get_doc/2, layout/2.

read_comments/1

read_comments(File) -> [comment()]

Equivalent to read_comments(File, []).

read_comments/2

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

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. See file/2 for options pertaining to reading source code files.

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

run/3

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

Run EDoc on a given set of source files and/or packages.

See also: files/2, packages/2.