👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for edoc (linux section 3erl)

edoc(3erl)			     Erlang Module Definition			       edoc(3erl)

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 for-
	   mat. 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 automati-
	      cally set up good defaults. Unless the user specifies otherwise:

		* The doc subdirectory will be used as the target directory, if it exists; other-
		  wise 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 documenta-
	      tion 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 cre-
	      ated 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_com-
	      ment_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  {prepro-
		  cess, false} .

		  Normally,  preprocessing  is not necessary for EDoc to work, but if a file con-
		  tains 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 avail-
		  able 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	automati-
		  cally 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::pro-
       plist()) -> 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 mod-
		  ule  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  con-
		  junction 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  sub-
		  packages 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  pack-
		  ages.

		{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 <richardc@it.uu.se >

					    edoc 0.7.7				       edoc(3erl)


All times are GMT -4. The time now is 04:18 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password