Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_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() = 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, 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/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()]

              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(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, 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.

                {packages, boolean()}:
                  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, 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}. 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 <carlsson.richard@gmail.com>

                                          edoc 0.7.12.1                                edoc(3erl)