edoc_run(3erl) [linux man page]
edoc_run(3erl) Erlang Module Definition edoc_run(3erl) NAME
edoc_run - Interface for calling EDoc from Erlang startup options. DESCRIPTION
Interface for calling EDoc from Erlang startup options. The following is an example of typical usage in a Makefile: docs: erl -noshell -run edoc_run application "'$(APP_NAME)'" '"."' '[{def,{vsn,"$(VSN)"}}]' (note the single-quotes to avoid shell expansion, and the double-quotes enclosing the strings). New feature in version 0.6.9 : It is no longer necessary to write -s init stop last on the command line in order to make the execution ter- minate. The termination (signalling success or failure to the operating system) is now built into these functions. EXPORTS
application(Args::[string()]) -> none() Calls edoc:application/3 with the corresponding arguments. The strings in the list are parsed as Erlang constant terms. The list can be either [App] , [App, Options] or [App, Dir, Options] . In the first case edoc:application/1 is called instead; in the second case, edoc:application/2 is called. The function call never returns; instead, the emulator is automatically terminated when the call has completed, signalling success or failure to the operating system. file(Args::[string()]) -> none() 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/1 , packages/1 and files/1 . Calls edoc:file/2 with the corresponding arguments. The strings in the list are parsed as Erlang constant terms. The list can be either [File] or [File, Options] . In the first case, an empty list of options is passed to edoc:file/2 . The following is an example of typical usage in a Makefile: $(DOCDIR)/%.html:%.erl erl -noshell -run edoc_run file '"$<"' '[{dir,"$(DOCDIR)"}]' -s init stop The function call never returns; instead, the emulator is automatically terminated when the call has completed, signalling success or failure to the operating system. files(Args::[string()]) -> none() Calls edoc:files/2 with the corresponding arguments. The strings in the list are parsed as Erlang constant terms. The list can be either [Files] or [Files, Options] . In the first case, edoc:files/1 is called instead. The function call never returns; instead, the emulator is automatically terminated when the call has completed, signalling success or failure to the operating system. packages(Args::[string()]) -> none() Calls edoc:application/2 with the corresponding arguments. The strings in the list are parsed as Erlang constant terms. The list can be either [Packages] or [Packages, Options] . In the first case edoc:application/1 is called instead. The function call never returns; instead, the emulator is automatically terminated when the call has completed, signalling success or failure to the operating system. SEE ALSO
edoc AUTHORS
Richard Carlsson <richardc@it.uu.se > edoc 0.7.7 edoc_run(3erl)
Check Out this Related Man Page
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 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 speci- fies 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 ), hyper- text 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 com- ments. 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_prepro- cess 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 struc- ture 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 <richardc@it.uu.se > edoc 0.7.7 edoc(3erl)