edoc(3)

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

    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() (see module //kernel/file) :

    package() = atom() | string() :

    proplist() = [term()] :

    syntaxTree() = syntaxTree() (see module //syntax_tools/erl_syntax) :

EXPORTS

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

    Equivalent to application(Application, []) .

application(Application::atom(), Options::proplist()) -> ok

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

    See also: application/1 .

application(Application::atom(), Dir::filename(), Options::proplist()) -> 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, 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::filename(), Options::proplist()) -> 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(Files::[filename() | {package(), [filename()]}]) -> ok

    Equivalent to packages(Packages, []) .

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

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

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

    Equivalent to get_doc(File, []) .

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

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

        {todo, bool()} :
            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/4 for further options.

    See also: get_doc/3 , layout/2 , read/2 , run/3 , edoc_extract:source/5 .

get_doc(File::filename(), Env::edoc_env() (see module edoc_lib), Options::proplist()) -> {ModuleName, edoc_module()}

    Types
        ModuleName = atom()

    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::proplist()) -> 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 , run/3 .

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

    Equivalent to packages(Packages, []) .

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

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

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

    Equivalent to read(File, []) .

read(File::filename(), Options::proplist()) -> 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(File) -> [comment()]

    Equivalent to read_comments(File, []) .

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

    Types
        {Line, Column, Indentation, Text}
        Line = integer()
        Column = integer()
        Indentation = integer()
        Text = [string()]

    Extracts comments from an Erlang source code file. See the module erl_comment_scan(3) 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::proplist()) -> [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. 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.

    See also: erl_syntax(3) , get_doc/2 .

run(Packages::[package()], Files::[filename() | {package(), [filename()]}], Options::proplist()) -> 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 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 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 .

AUTHORS

Richard Carlsson <richardc@it.uu.se >