Provided by: erlang-manpages_25.3.2.8+dfsg-1ubuntu4_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() = erl_comment_scan:comment():

         edoc_module() = xmerl_scan:xmlElement():

           The  EDoc  documentation  data  for  a  module,  expressed as an XML document in XMerL
           format. See the file edoc.dtd for details.

         entry() = #entry{name=function_name() | atom(), args=[atom() | list()],  line=integer(),
         export=boolean(), data=entry_data()}:

           Module Entries (one per function, plus module header and footer).

         entry_data() = term():

         env() = #env{}:

           Environment information needed by EDoc for generating references.

         filename() = file:filename():

         function_name() = {atom(), integer()}:

         module_meta()    =    #module{name=[]    |    atom(),    parameters=none   |   [atom()],
         functions=ordset(function_name()),                      exports=ordset(function_name()),
         attributes=ordset({atom(),    term()}),    records=[{atom(),    [{atom(),    term()}]}],
         encoding=epp:source_encoding(), file=file:filename()}:

           Module information.

         ordset(T) = ordsets:ordset(T):

         proplist() = proplists:proplist():

         syntaxTree() = erl_syntax:syntaxTree():

         tag()  =  #tag{name=atom(),  line=integer(),   origin=comment   |   code,   data=term(),
         form=undefined | erl_parse:abstract_form()}:

           Generic tag information. #tag.form is only defined if #tag.origin is code, that is the
           #tag{} represents a code fragment, not a doc comment tag.

EXPORTS

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

              Equivalent to application(Application, []).

       application(App, Options) -> ok

              Types:

                 App = atom()
                 Options = proplist()

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

              See also: application/1.

       application(App, Dir, Options) -> ok

              Types:

                 App = atom()
                 Dir = filename()
                 Options = proplist()

              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, Options) -> ok

              Types:

                 Name = filename()
                 Options = proplist()

              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, Options) -> ok

              Types:

                 Files = [filename()]
                 Options = proplist()

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

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

              Equivalent to get_doc(File, []).

       get_doc(File, Options) -> R

              Types:

                 File = filename()
                 Options = proplist()
                 R = {module(), edoc_module()} | {module(), edoc_module(), [entry()]}

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

                  * MacroFun       =        fun((MacroArgument::string(),        Line::integer(),
                    edoc_lib:edoc_env()) -> (Text::string()))

                  Specifies  a  set  of  user-defined EDoc macros. The text substituted for macro
                  calls is specified as either a string() or a function(). The function is called
                  with  the  macro  argument  text,  the  current  line  number,  and the current
                  environment. The fun is to return a string(). See 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, Env, Options) -> R

              Types:

                 File = filename()
                 Env = env()
                 Options = proplist()
                 R = {module(), edoc_module()} | {module(), edoc_module(), [entry()]}

              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, Opts) -> string()

              Types:

                 Doc = edoc_module()
                 Opts = proplist()

              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, Opts) -> string()

              Types:

                 File = filename()
                 Opts = proplist()

              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::filename()) -> [comment()]

              Equivalent to read_comments(File, []).

       read_comments(File, Opts) -> [comment()]

              Types:

                 File = filename()
                 Opts = proplist()

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

       read_source(Name::filename()) -> [syntaxTree()]

              Equivalent to read_source(File, []).

       read_source(File, Opts) -> [syntaxTree()]

              Types:

                 File = filename()
                 Opts = proplist()

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

                {link_predefined_types, boolean()}:
                  If  the value is true, all predefined data types will have a link to the erlang
                  module. This option is  to  be  used  when  generating  documentation  for  the
                  Erlang/OTP  docs.  The  default  value is false. no_link_predefined_types is an
                  alias for {link_predefined_types, false}.

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

       run(Files, Opts) -> ok

              Types:

                 Files = [filename()]
                 Opts = proplist()

              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  file  system paths pointing to directories that contain
                  EDoc-generated documentation. All paths for applications in the code  path  are
                  automatically added.

                {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 1.2                                  edoc(3erl)