Copyright © 2001-2003 Richard Carlsson
Version: 0.4 beta
Authors: Richard Carlsson (richardc@csd.uu.se) [web site: http://www.csd.uu.se/~richardc/].
This module provides the main user interface to EDoc.
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() = //kernel/file:filename()
option_list() = [term()]
| 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 | Run 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 documentation data to text. |
| packages/1 | Equivalent to packages(Packages, []). |
| packages/2 | Run EDoc on a set of packages. |
| read/1 | Equivalent to read(File, []). |
| read/2 | Like file/2, but returns the resulting text directly
instead of writing to a file. |
| 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 | Run EDoc on a given set of source files and/or packages. |
application(Application::atom()) -> ok
Equivalent to application(Application, []).
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(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(Name::filename()) -> ok
Equivalent to file(Name, []).
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}get_doc/2 for details.{dir, filename()}{file_suffix, string()}".html".{layout, atom()}layout/2 for
details.{preprocess, bool()}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()]}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()}]}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(Files::[filename() | {package(), [filename()]}]) -> ok
Equivalent to packages(Packages, []).
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(File::filename()) -> {ModuleName, edoc_module()}
Equivalent to get_doc(File, []).
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}Macros = Macro | [Macro]Macro = {Name::atom(), Text::string()}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(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(Doc::edoc_module()) -> string()
Equivalent to layout(Doc, []).
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()}edoc_layout.See also: get_doc/2, edoc_layout:module/2.
packages(Packages::[package()]) -> ok
Equivalent to packages(Packages, []).
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(File::filename()) -> string()
Equivalent to read(File, []).
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(File) -> [comment()]
Equivalent to read_comments(File, []).
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(Name::File) -> [syntaxTree()]
Equivalent to read_source(File, []).
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(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.