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.