Provided by: erlang-manpages_22.2.7+dfsg-1_all bug

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

         comment() = {Line, Column, Indentation, Text}:

           * Line = integer()

           * Column = integer()

           * Indentation = integer()

           * Text = [string()]

         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() = file:filename():

         proplist() = [term()]:

         syntaxTree() = erl_syntax:syntaxTree():

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/2 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 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()]) -> ok

       files(Files::[filename()], Options::proplist()) -> ok

              Runs EDoc on a given set of source files. See run/2 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, boolean()}:
                  If  the value is true, documentation of hidden functions will also be included.
                  The default value is false.

                {private, boolean()}:
                  If the value is true, documentation of private functions will also be included.
                  The default value is false.

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

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

       get_doc(File::filename(), Env::edoc_lib:edoc_env(), 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/3.

       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/2.

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

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

                {report_missing_types, boolean()}:
                  If  the value is true, warnings are issued for missing types. The default value
                  is  false.  no_report_missing_types  is  an  alias  for  {report_missing_types,
                  false}.

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

       run(Files::[filename()], Options::proplist()) -> ok

              Runs  EDoc  on  a given set of source files. 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.

                {file_suffix, string()}:
                  Specifies  the suffix used for output files. The default value is ".html". Note
                  that this also affects generated references.

                {new, boolean()}:
                  If the value is true, any existing edoc-info file in the target directory  will
                  be ignored and overwritten. The default value is false.

                {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, boolean()}:
                  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}.

                  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.

AUTHORS

       Richard Carlsson <carlsson.richard@gmail.com>

                                            edoc 0.11                                  edoc(3erl)