Anda di halaman 1dari 48

EDoc Application

version 0.7

A Typeset in L TEX from SGML source using the DocBuilder-0.9.8.4 Document System.

Contents
1 EDoc Users Guide 1.1 Welcome to EDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.3 Running EDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.4 The overview page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.5 Generic tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.6 Overview tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.7 Module tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.8 Function tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.9 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.10 Notes on XHTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.11 Wiki notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.12 Macro expansion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.13 Type specications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.14 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 EDoc Reference Manual 2.1 2.2 2.3 2.4 2.5 2.6 edoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . edoc doclet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . edoc extract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . edoc layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . edoc lib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . edoc run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1 1 2 2 3 3 4 5 6 7 7 8 10 12 14 17 22 28 30 33 34 37

List of Tables

39

EDoc Application

iii

iv

EDoc Application

Chapter 1

EDoc Users Guide


EDoc is the Erlang program documentation generator. Inspired by the Javadoc (TM) tool for the Java (TM) programming language, EDoc is adapted to the conventions of the Erlang world, and has several features not found in Javadoc.

1.1

Welcome to EDoc

EDoc is the Erlang program documentation generator. Inspired by the Javadoc(TM) tool for the Java(TM) programming language, EDoc is adapted to the conventions of the Erlang world, and has several features not found in Javadoc.

1.1.1 Contents
Introduction [page 2] Running EDoc [page 2] The overview page [page 3] Generic tags [page 3] Overview tags [page 4] Module tags [page 5] Function tags [page 6] References [page 7] Notes on XHTML [page 7] Wiki notation [page 8] Macro expansion [page 10] Type specications [page 12] Acknowledgements [page 14]

EDoc Application

Chapter 1: EDoc Users Guide

1.1.2 Introduction
EDoc lets you write the documentation of an Erlang program as comments in the source code itself, using tags on the form @Name .... A source le does not have to contain tags for EDoc to generate its documentation, but without tags the result will only contain the basic available information that can be extracted from the module. A tag must be the rst thing on a comment line, except for leading % characters and whitespace. The comment must be between program declarations, and not on the same line as any program text. All the following text - including consecutive comment lines - up until the end of the comment or the next tagged line, is taken as the content of the tag. Tags are associated with the nearest following program construct of signicance (the module name declaration and function denitions). Other constructs are ignored; e.g., in: %% @doc Prints the value X. -record(foo, x, y, z ). print(X) ...

the @doc tag is associated with the function print/1. Note that in a comment such as: % % @doc ... the tag is ignored, because only the rst % character is considered leading. This allows tags to be commented out. Some tags, such as @type, do not need to be associated with any program construct. These may be placed at the end of the le, in the footer.

1.1.3 Running EDoc


The following are the main functions for running EDoc:

edoc:application/2 [page 22]: Creates documentation for a typical Erlang application. edoc:packages/2 [page 25]: Creates documentation for one or more packages, automatically locating source les. edoc:les/2 [page 23]: Creates documentation for a specied set of source les. edoc:run/3 [page 26]: General interface function; the common back-end for the above functions. Options are documented here.
Note that the function edoc:le/2 [page 23] belongs to the old, deprecated interface (from EDoc version 0.1), and should not be used.

EDoc Application

1.1: Welcome to EDoc

1.1.4 The overview page


When documentation is generated for an entire application, an overview page, or front page, is generated. (The page you are now reading is an overview page.) This should contain the high-level description or user manual for the application, leaving the ner details to the documentation for individual modules. By default, the overview page is generated from the le overview.edoc in the target directory (typically, this is the doc subdirectory of the application directory); see edoc doclet [page 28] for details. The format of the overview le is the same as for EDoc documentation comments (see Introduction [page 2]), except that the lines do not have leading % characters. Furthermore, all lines before the rst tag line are ignored, and can be used as a comment. All tags in the overview le, such as @doc, @version, etc., refer to the application as a whole; see Overview tags [page 4] for details. Here is an example of the contents of an overview le: ** this is the overview.doc file for the application frob ** @author R. J. Hacker rjh@acme.com @copyright 2007 R. J. Hacker @version 1.0.0 @title Welcome to the frob application! @doc frob is a highly advanced frobnicator with low latency, ...

1.1.5 Generic tags


The following tags can be used anywhere within a module: @clear This tag causes all tags above it (up to the previous program construct), to be discarded, including the @clear tag itself. The text following the tag is also ignored. This is typically only useful in code containing conditional compilation, when preprocessing is turned on. (Preprocessing is turned off by default.) E.g., in -ifdef(DEBUG). %% @doc ... foo(...) - ... -endif. %% @clear %% @doc ... bar(...) - ... the @clear tag makes sure that EDoc does not see two @doc tags before the function bar, even if the code for function foo is removed by preprocessing. (There is no way for EDoc to see what the rst @doc tag really belongs to, since preprocessing strips away all such information.) @docfile Reads a plain documentation le (on the same format as an overview le - see The overview page [page 3] for details), and uses the tags in that le as if they had been written in place of the @docfile tag. The content is the name of the le to be read; leading and trailing whitespace is ignored. See also @headerle [page 4]. @end The text following this tag is always ignored. Use this to mark the end of the previous tag, when necessary, as e.g. in:

EDoc Application

Chapter 1: EDoc Users Guide %% %% %% %% %% %% ---------------------------------... @doc ... ... @end ----------------------------------

to avoid including the last ruler line in the @doc tag. Note: using some other dummy @-tag for the same purpose might work in a particular implementation of EDoc, but is not guaranteed to. Always use @end to ensure future compatibility. @headerfile Similar to the @docle tag [page 3], but reads a le containing Erlang source code generally this should be a header le (with the extension .hrl). If the le turns out to contain one or more function denitions or a module declaration, all tags that occur above the last such denition or module declaration are ignored, and EDoc will print a warning. This tag allows you to write documentation in a header le and insert it at a specic place in the documentation, even if the header le is used (i.e., included) by several modules. The includes option can be used to specify a search path (see edoc:read source/2 [page 25]). @todo (or @TODO) Attaches a To-Do note to a function, module, package, or overview-page. The content can be any XHTML text describing the issue, e.g.: %% @TODO Finish writing the documentation. or %% @todo Implement a href="http://www.ietf.org/rfc/rfc2549.txt" RFC 2549 /a .

These tags can also be written as TODO:, e.g.: %% TODO: call your mother see Wiki notation [page 8] for more information. To-Do notes are normally not shown unless the todo option is turned on (see edoc:get doc/2 [page 24]). @type Documents an abstract data type or type alias. The content consists of a type declaration or denition, optionally followed by a period (.) separator and XHTML text describing the type (i.e., its purpose, use, etc.). There must be at least one whitespace character between the . and the text. See Type specications [page 12] for syntax and examples. All data type descriptions are placed in a separate section of the documentation, regardless of where the tags occur.

1.1.6 Overview tags


The following tags can be used in an overview le. @author See the @author module tag [page 5] for details. @copyright See the @copyright module tag [page 5] for details. @doc See the @doc module tag [page 5] for details. @reference See the @reference module tag [page 5] for details. @see See the @see module tag [page 6] for details. @since See the @since module tag [page 6] for details. @title Species a title for the overview page. This tag can only be used in an overview le. The content can be arbitrary text.

EDoc Application

1.1: Welcome to EDoc @version See the @version module tag [page 6] for details.

1.1.7 Module tags


The following tags can be used before a module declaration: @author Species the name of an author, along with contact information. An e-mail address can be given within ... delimiters, and a URI within [...] delimiters. Both e-mail and URI are optional, and any surrounding whitespace is stripped from all strings. The name is the rst nonempty string that is not within ... or [...], and does not contain only whitespace. (In other words, the name can come before, between, or after the e-mail and URI, but cannot be split up; any sections after the rst are ignored.) If an e-mail address is given, but no name, the e-mail string will be used also for the name. If no ... section is present, but the name string contains an @ character, it is assumed to be an e-mail address. Not both name and e-mail may be left out. Examples: %% @author Richard Carlsson %% @author Richard Carlsson richardc@it.uu.se %% [http://user.it.uu.se/~richardc/] %% @author richardc@it.uu.se

%% @author richardc@it.uu.se [http://user.it.uu.se/~richardc/] @copyright Species the module copyrights. The content can be arbitrary text; for example: %% @copyright 2001-2003 Richard Carlsson @deprecated Mark the module as deprecated, indicating that it should no longer be used. The content must be well-formed XHTML, and should preferably include a @link reference to a replacement; as in: %% @deprecated Please use the module @link foo instead.

@doc Describes the module, using well-formed XHTML text. The rst sentence is used as a summary (see the @doc function tag [page 6] for details). For example.: %% @doc This is a em very /em useful module. It is ...

@hidden Marks the module so that it will not appear in the documentation (even if private documentation is generated). Useful for sample code, test modules, etc. The content can be used as a comment; it is ignored by EDoc. @private Marks the module as private (i.e., not part of the public interface), so that it will not appear in the normal documentation. (If private documentation is generated, the module will be included.) The content can be used as a comment; it is ignored by EDoc. @reference Species a reference to some arbitrary external resource, such as an article, book, or web site. The content must be well-formed XHTML text. Examples: %% @reference Pratchett, T., em Interesting Times /em , %% Victor Gollancz Ltd, 1994.

EDoc Application

Chapter 1: EDoc Users Guide %% @reference See a href="www.google.com" Google /a %% more information. @see See the @see function tag [page 6] for details. @since Species when the module was introduced, with respect to the application, package, release or distribution it is part of. The content can be arbitrary text. @version Species the module version. The content can be arbitrary text. for

1.1.8 Function tags


The following tags can be used before a function denition: @deprecated See the @deprecated module tag [page 5] for details. @doc XHTML text describing the function. The rst sentence of the text is used as a quick summary; this ends at the rst period character (.) or exclamation mark (!) that is followed by a whitespace character, a line break, or the end of the tag text, and is not within XML markup. (As an exception, the rst sentence may be within an initial paragraph element) @equiv Specify equivalence to another function call/expression. The content must be a proper Erlang expression. If the expression is a function call, a cross-reference to the called function is created automatically. Typically, this tag is used instead of @doc. @hidden Marks the function so that it will not appear in the documentation (even if private documentation is generated). Useful for debug/test functions, etc. The content can be used as a comment; it is ignored by EDoc. @private Marks the function as private (i.e., not part of the public interface), so that it will not appear in the normal documentation. (If private documentation is generated, the function will be included.) Only useful for exported functions, e.g. entry points for spawn. (Non-exported functions are always private.) The content can be used as a comment; it is ignored by EDoc. @see Make a reference to a module, function, datatype, or application. (See References [page 7].) The content consists of a reference, optionally followed by a period (.), one or more whitespace characters, and XHTML text to be used for the label; for example @see edoc or @see edoc. b EDoc /b . If no label text is specied, the reference itself is used as the label. @since Species in what version of the module the function was introduced; cf. the @version module tag [page 6]. The content can be arbitrary text. @spec Used to specify the function type; see Type specications [page 12] for syntax details. If the function name is included in the specication, it must match the name in the actual code. When parameter names are not given in the specication, suitable names will be taken from the source code if possible, and otherwise synthesized. @throws Species which types of terms may be thrown by the function, if its execution terminates abruptly due to a call to erlang:throw(Term). The content is a type expression (see Type specications [page 12]), and can be a union type. Note that exceptions of type exit (as caused by calls to erlang:exit(Term)) and error (run-time errors such as badarg or badarith) are not viewed as part of the normal interface of the function, and cannot be documented with the @throws tag. @type See the @type generic tag [page 4] for details. Placing a @type tag by a function denition may be convenient, but does not affect where the description is placed in the generated documentation.

EDoc Application

1.1: Welcome to EDoc

1.1.9 References
In several contexts (@see tags, @link macros, etc.), EDoc lets you refer to the generated documentation for modules, functions, datatypes, and applications, using a simple and compact syntax. The possible formats for references are:

Reference syntax Module Package.* Function/Arity Module:Function/Arity Type() Module:Type() //Application //Application/Module //Application/Module:Function/Arity //Application/Module:Type()

Example edoc run [page 37], erl.lang.list erl.lang.* file/2 edoc:application/2 [page 22] filename() edoc:edoc module() [page 22] [edoc] [edoc doclet(3)] [edoc run:le/1] [edoc:edoc module()]

Scope Global Global Within module Global Within module Global Global Global Global Global

Table 1.1: reference syntax

EDoc will resolve references using the information it nds in edoc-info-les at the locations specied with the doc path option. EDoc will automatically (and somewhat intelligently) try to nd any local edoc-info-les using the current code path, and add them to the end of the doc path list. The target doc-directory is also searched for an existing info le; this allows documentation to be built incrementally. (Use the new option to ignore any old info le.) Note that if the name of a module, function or datatype is explicitly qualied with an application (as in //edoc/edoc run), this overrides any other information about that name, and the reference will be made relative to the location of the application (if it can be found). This makes it possible to refer to e.g. a module fred as //foo/fred without accidentally getting a reference to //bar/fred. You should not use this form of explicit references for names that are local to the application you are currently creating - they will always be resolved correctly. Note that module-local references such as file/2 only work properly within a module. In an overview-page like this (i.e., the one you are currently reading), no module context is available.

1.1.10 Notes on XHTML


In several places, XHTML markup can be used in the documentation text, in particular in @doc tags. The main differences from HTML are the following:

All elements must have explicit start and end tags, and be correctly nested. This means that you cannot e.g. write a li tag without also writing a corresponding /li tag in the right place. This could be an annoyance at times, but has the great advantage that EDoc can report all malformed XHTML in your source code, rather than propagate the errors to the generated documentation. XHTML tag and attribute names should always be lower-case. Attributes must be quoted, as in e.g.
a name="top" .

EDoc Application

Chapter 1: EDoc Users Guide To write an element like the HTML br , which has no actual content, you can write either the full br /br , or better, use the XHTML abbreviated form br/ . Since the purpose of EDoc is to document programs, there is also a limited form of wiki-syntax available for making program code easier to write inline (and to make the doc-comments easier to read). See Wiki notation [page 8] for details. The HTML heading tags h1 and h2 are reserved for use by EDoc. Headings in documentation source code should start at h3. There is however a special syntax for writing headings which avoids using specic level numbers altogether; see Headings [page 9] for details. EDoc uses [XMerL] to parse and export XML markup.

1.1.11

Wiki notation

When EDoc parses XHTML, it does additional pre- and post-processing of the text in order to expand certain notation specic to EDoc into proper XHTML markup. This wiki ( http://en.wikipedia.org/wiki/Wiki1 ) notation is intended to make it easier to write source code documentation. Empty lines separate paragraphs Leaving an empty line in XHTML text (i.e., a line which except for any leading start-of-comment % characters contains only whitespace), will make EDoc split the text before and after the empty line into separate paragraphs. For example: %% %% %% %% %% %% %% @doc This will all be part of the first paragraph. It can stretch over several lines and contain em any XHTML markup /em . This is the second paragraph. The above line is regarded as "empty" by EDoc, even though it ends with a space.

will generate the following text: This will all be part of the rst paragraph. It can stretch over several lines and contain any XHTML markup. This is the second paragraph. The above line is regarded as empty by EDoc, even though it ends with a space. Paragraph splitting takes place after the actual XHTML parsing. It only affects block-level text, and not e.g., text within pre markup, or text that is already within p markup.
1 URL:

http://en.wikipedia.org/wiki/Wiki

EDoc Application

1.1: Welcome to EDoc Headings Section headings, sub-headings, and sub-sub-headings, can be written using the following notation: == Heading == === Sub-heading === ==== Sub-sub-heading ==== Such a heading must be alone on a line, except for whitespace, and cannot be split over several lines. A link target is automatically created for the heading, by replacing any whitespace within the text by a single underscore character. E.g., == Concerning Hobbits == is equivalent to h3 a name="Concerning Hobbits" Concerning Hobbits /a /h3

Thus, headings using this notation should not contain characters that may not be part of URL labels, except for whitespace. If you need to create such headings, you have to use the explicit XHTML markup. A hypertext link to a heading written this way can be created using the @section macro, which transforms the argument text into a label as described above. E.g., @section Concerning Hobbits is eqivalent to writing a href="#Concerning Hobbits" Concerning Hobbits /a The above expansions take place before XML parsing. External links Writing a URL within brackets, as in [http://www.w3c.org/], will generate a hyperlink such as http://www.w3c.org/2, using the URL both for the destination and the label of the reference, equivalent tt http://www.w3c.org/ /tt /a . This to writing a href="http://www.w3c.org/" short-hand keeps external URL references short and readable. The recognized protocols are http, ftp, and file. This expansion takes place before XML parsing. TODO-notes Lines that begin with the text TODO: (the colon is required) are recognized as tags, as if they had been written as @todo ... (see @todo tags [page 4] for further details).
2 URL:

http://www.w3c.org/

EDoc Application

Chapter 1: EDoc Users Guide Verbatim quoting In XHTML text, the character (Unicode 000060, known as grave accent or back-quote) can be used for verbatim quoting. This expansion takes place before XML parsing.

A character sequence ... or ... will be expanded to code ... /code , where all occurrences of the special XML characters and & (and for completeness, also ) in the quoted text have been escaped to <, &, and >, respectively. All whitespace is stripped from the beginning and end of the quoted text. Double back-quotes ... can be used to quote text containing single characters. The automatic stripping of any surrounding whitespace makes it possible to write things like foo@bar . To quote text containing verbatim, explicit code markup or similar must be used. A character sequence ... will be expanded to pre ![CDATA[...]] /pre , which disables all XML markup within the quoted text, and displays the result in xed-font with preserved indentation. Whitespace is stripped from the end of the quoted text, but not from the beginning, except for whole leading lines of whitespace. This is useful for multi-line code examples, or displayed one-liners. To produce a single -character in XML without beginning a new quote, you can write (no space between the and the ). You can of course also use the XML character entity `.
Examples: %% @doc ...where the variable Foo refers to... %% @doc ...returns the atom foo@erlang.org ... %% @doc ...use the command erl -name foo to... %% @doc ...as in the following code: %% f(X) %% case X of %% ... %% end %% @doc ...or in the following: %% %% g(X) %% fun () - ... end %%

1.1.12

Macro expansion

Before the content of a tag is parsed, the text undergoes macro expansion. The syntax for macro calls is: @name or @name argument

10

EDoc Application

1.1: Welcome to EDoc where name and argument are separated by one or more whitespace characters. The argument can be any text, which may contain other macro calls. The number of non-escaped @ and delimiters must be balanced. The argument text is rst expanded in the current environment, and the result is bound to the macro parameter , written @? . (If no argument is given, @? is bound to the empty string.) The macro denition is then substituted for the call, and expansion continues over the resulting text. Recursive macro expansions are not allowed. User-dened macros Users can dene their own macros by using the def EDoc option; see edoc:le/2 [page 23] and edoc:get doc/2 [page 24] for more information. User-dened macros override predened macros. Predened macros @date Expands to the current date, as Month Day Year, e.g. Nov 5 2008. @docRoot Expands to the relative URL path (such as "../../..") from the current page to the root directory of the generated documentation. This can be used to create XHTML references such as img src=" @docRoot /images/logo.jpeg" that are independent of how deep down in a package structure they occur. If packages are not used (i.e., if all modules are in the empty package), @docRoot will always resolve to the empty string. @link reference. description This creates a hypertext link; cf. the @see function tag [page 6] above for details. The description text (including the period separator) is optional; if no text is given, the reference itself is used. For example, @link edoc:file/2 creates the link edoc:le/2 em this link /em creates this link [page 23]. [page 23], and @link edoc:file/2. @module Expands to the name of the current module. Only dened when a module is being processed. @package Expands to the name of the current package. @section heading Expands to a hypertext link to the specied section heading; see Headings [page 9] for more information. @time Expands to the current time, as Hr:Min:Sec, e.g. 11:38:58. @type type-expression Formats a type expression within code ... /code markup and with hypertext links for data types. For example, @type options, List::edoc:option list()@ generates options, List::edoc:option list() . (Cf. Escape sequences [page 11].) @version Intended for use in @version tags [page 6]. Defaults to a timestamp using @date and @time . Typically, this macro is redened by the user when an ofcial release of the application is generated. Escape sequences To prevent certain characters from being interpreted as delimiters, for example to produce the text @ in the output, or use a character in the argument text of a macro call, the following escape sequences may be used: @ Expands to . Example: %% @doc A macro call starts with the sequence "@ @".

EDoc Application

11

Chapter 1: EDoc Users Guide @ Expands to . Example: %% @doc ... @foo ... Key, Value@ ... ... @@ Expands to @. Example: %% @doc Contact us at support@@ @hostname Will generate the text Contact us at support@vaporware.acme.com if the macro hostname is bound to vaporware.acme.com. Also: %% @doc You might want to write something like %% @@foo that will expand to @foo and does not start %% a new tag even if it appears first in a line.

1.1.13

Type specications

Function specications The following grammar describes the form of the specications following a @spec tag. A ? sufx implies that the element is optional. Function types have higher precedence than union types; e.g., (atom()) - atom() | integer() is parsed as ((atom()) - atom()) | integer(), not as (atom()) - (atom() | integer()). Spec ::= FunType "where"? DefList? | FunctionName FunType "where"? DefList? FunctionName ::= Atom FunType ::= "(" UnionTypes? ")" "- " UnionType UnionTypes ::= UnionType | UnionType "," UnionTypes UnionType ::= UnionList | Name "::" UnionList Name ::= Variable UnionList ::= Type | Type "+" UnionList | Type "|" UnionList Type ::= TypeVariable | Atom | Integer | Float | FunType | " " UnionTypes? " " | "[" "]" | "[" UnionType "]" | "(" UnionType ")" | TypeName "(" UnionTypes? ")" | ModuleName ":" TypeName "(" UnionTypes? ")" | "//" AppName "/" ModuleName ":" TypeName "(" UnionTypes? ")" TypeVariable ::= Variable TypeName ::= Atom ModuleName ::= Atom | ModuleName "." Atom AppName ::= Atom DefList ::= Def | DefList Def | DefList "," Def Def ::= TypeVariable "=" UnionType | TypeName "(" TypeVariables? ")" "=" UnionType TypeVariables ::= TypeVariable | TypeVariable "," TypeVariables Examples: %% @spec my function(X::integer()) %% @spec (X::integer()) %% @spec sqrt(float()) %% @spec pair(S, T) integer() float() S, T integer()

12

EDoc Application

1.1: Welcome to EDoc %% @spec append(List, List) %% List = [term()] List

%% @spec append(A::List, B::List) %% List = [Item] %% Item = term()

List

%% @spec open(File::filename()) - FileDescriptor %% where %% filename() = string() + atom(), %% FileDescriptor = term() %% @spec close(graphics:window()) ok

In the above examples, X, A, B, and File are parameter names, used for referring to the parameters from the documentation text. The type variables S, T and List are used to simplify the type specications, and may be supplied with denitions. It is also possible to give denitions for named types, which means that the name is simply an alias. (Use the @type tag to document abstract data types.) If a named type is dened in another module, it can be referred to as Module:TypeName(...). Note that the keyword where is optional before a list of denitions, and that the denitions in the list may optionally be separated by ,. Both the | and the + character may be used to separate alternatives in union types; there is no semantic difference. Note that the notation [Type] means proper (nil-terminated) list whose elements all belong to Type; For example, [atom()|integer()] means the same thing as [atom()+integer()], i.e., a proper list of atoms and/or integers. If only a type variable is given for a parameter, as in pair(S, T) - ..., the same variable name may implicitly be used as the parameter name; there is no need to write pair(S::S, T::T) - .... EDoc automatically extracts possible parameter names from the source code, to be used if no parameter name is given in the specication (or if the specication is missing altogether). If this fails, EDoc will generate a dummy parameter name, such as X1. This way, EDoc can often produce helpful documentation even for code that does not contain any annotations at all. Type denitions The following grammar (see above for auxiliary denitions) describes the form of the denitions that may follow a @type tag: Typedef ::= TypeName "(" TypeVariables? ")" DefList? | TypeName "(" TypeVariables? ")" "=" UnionType DefList? (For a truly abstract data type, no equivalence is specied.) The main denition may be followed by additional local denitions. Examples: %% @type myList(X). A special kind of lists ... %% @type filename() = string(). Atoms not allowed! %% @type thing(A) = thong, A %% A = term(). %% A kind of wrapper type thingy.

EDoc Application

13

Chapter 1: EDoc Users Guide Pre-dened data types The following data types are predened by EDoc, and may not be redened: any() atom() binary() bool() char() cons() deep string() float() function() integer() list() nil() none() number() pid() port() reference() string() term() tuple() Details:

any() means any Erlang data type. term() is simply an alias for any(). atom(), binary(), float(), function(), integer(), pid(), port() and reference() are primitive data types of the Erlang programming language. bool() is the subset of atom() consisting of the atoms true and false. char() is a subset of integer() representing character codes. tuple() is the set of all tuples ... . list(T) is just an alias for [T]. nil() is an alias for the empty list []. cons(H,T) is the list constructor. This is usually not used directly. It is possible to recursively dene list(T) := nil()+cons(T,list(T)). string() is an alias for [char()]. deep string() is recursively dened as [char()+deep string()]. none() means no data type. E.g., a function that never returns has type (...)
none()

1.1.14

Acknowledgements

Since the rst version of EDoc, several people have come up with suggestions (Luke Gorrie, Joe Armstrong, Erik Stenman, Sean Hinde, Ulf Wiger, ...), and some have even submitted code to demonstrate their ideas (Vlad Dumitrescu, Johan Blom, Vijay Hirani, ...). None of that code was actually included in the Great Rewriting that followed the initial public release (EDoc version 0.1), but most of the central points were addressed in the new system, such as better modularization and

14

EDoc Application

1.1: Welcome to EDoc possibility to plug in different layout engines, and making EDoc understand the application directory layout. It is now getting too hard to keep track of all the people who have made further suggestions or submitted bug reports, but your input is always appreciated. Thank you.

EDoc Application

15

Chapter 1: EDoc Users Guide

16

EDoc Application

EDoc Reference Manual


Short Summaries
Erlang Module edoc [page 22] EDoc - the Erlang program documentation generator. Erlang Module edoc doclet [page 28] Standard doclet module for EDoc. Erlang Module edoc extract [page 30] EDoc documentation extraction. Erlang Module edoc layout [page 33] The standard HTML layout module for EDoc. Erlang Module edoc lib [page 34] Utility functions for EDoc. Erlang Module edoc run [page 37] Interface for calling EDoc from Erlang startup options.

edoc
The following functions are exported:

application(Application::atom()) - ok [page 22] Equivalent to application(Application, []). application(Application::atom(), Options::proplist()) [page 22] Run EDoc on an application in its default app-directory.
ok

application(Application::atom(), Dir::filename(), Options::proplist()) - ok [page 22] Run EDoc on an application located in the specied directory. file(Name::filename()) - ok [page 23] Equivalent to le(Name, []). file(Name::filename(), Options::proplist()) - ok [page 23] Reads a source code le and outputs formatted documentation to a corresponding le. files(Files::[filename() | package(), [filename()] ]) [page 23] Equivalent to packages(Packages, []). files(Files::[filename() | package(), [filename()] ], Options::proplist()) - ok [page 23] Runs EDoc on a given set of source les. get doc(File::filename()) ModuleName, edoc module() [page 23] Equivalent to get doc(File, []).
ok

EDoc Application

17

EDoc Reference Manual

get doc(File::filename(), Options::proplist()) ModuleName, edoc module() [page 23] Reads a source code le and extracts EDoc documentation data. get doc(File::filename(), Env::edoc env() (see module edoc lib), ModuleName, edoc module() Options::proplist()) [page 23] Like get doc/2, but for a given environment parameter. layout(Doc::edoc module()) - string() [page 24] Equivalent to layout(Doc, []). layout(Doc::edoc module(), Options::proplist()) - string() [page 24] Transforms EDoc module documentation data to text. packages(Packages::[package()]) - ok [page 24] Equivalent to packages(Packages, []). packages(Packages::[package()], Options::proplist()) [page 24] Runs EDoc on a set of packages. read(File::filename()) - string() [page 25] Equivalent to read(File, []). read(File::filename(), Options::proplist()) - string() [page 25] Reads and processes a source le and returns the resulting EDoc-text as a string. read comments(File) - [comment()] [page 25] Equivalent to read comments(File, []). read comments(File::filename(), Options::proplist()) [page 25] Extracts comments from an Erlang source code le. read source(Name::File) - [syntaxTree()] [page 25] Equivalent to read source(File, []). read source(File::filename(), Options::proplist()) - [syntaxTree()] [page 25] Reads an Erlang source le and returns the list of source code form syntax trees. run(Packages::[package()], Files::[filename() | package(), [filename()] ], Options::proplist()) - ok [page 26] Runs EDoc on a given set of source les and/or packages.
[comment()] ok

edoc doclet
The following functions are exported:

run(Command::doclet gen() | doclet toc(), Ctxt::edoc context()) ok [page 28] Main doclet entry point.

edoc extract
The following functions are exported:

file(File::filename(), Context, Env::edoc env(), ok, Tags | error, Reason Options::proplist()) [page 30] Reads a text le and returns the list of tags in the le.

18

EDoc Application

EDoc Reference Manual

header(File::filename(), Env::edoc env(), Options::proplist()) ok, Tags | error, Reason [page 30] Similar to header/5, but reads the syntax tree and the comments from the specied le. header(Forms, File::filename(), Env::edoc env(), ok, Tags | error, Reason Options::proplist()) [page 30] Extracts EDoc documentation from commented header le syntax trees. header(Forms, Comments::[comment()], File::filename(), ok, Tags | error, Env::edoc env(), Options::proplist()) Reason [page 30] Similar to header/4, but rst inserts the given comments in the syntax trees. source(File::filename(), Env::edoc env(), Options::proplist()) ModuleName, edoc module() [page 31] Like source/5, but reads the syntax tree and the comments from the specied le. source(Forms, File::filename(), Env::edoc env(), ModuleName, edoc module() Options::proplist()) [page 31] Extracts EDoc documentation from commented source code syntax trees. source(Forms, Comments::[comment()], File::filename(), ModuleName, edoc module() Env::edoc env(), Options::proplist()) [page 31] Like source/4, but rst inserts the given comments in the syntax trees. text(Text::string(), Context, Env::edoc env(), Options::proplist()) - Tags [page 32] Returns the list of tags in the text.

edoc layout
The following functions are exported:

module(Element, Options) [page 33] The layout function. overview(E, Options) [page 33] package(E, Options) [page 33] type(E) [page 33]
term()

term()

term() term()

edoc lib
The following functions are exported:

copy file(From, To) [page 34] count(X, Xs) [page 34]


term()

term()

EDoc Application

19

EDoc Reference Manual

datestr(X1) [page 34]

term() term()

escape uri(Cs) [page 34] filename(T) [page 34]

term() term() term() term()

find doc dirs() [page 34]

find file(Ps, Pkg, Name) [page 34] find sources(Path, Opts) [page 34]

find sources(Path, Pkg, Opts) - term() [page 34] See edoc:run/3 for a description of the options subpackages, source sufx and exclude packages. get doc env(Options::proplist()) - edoc env() [page 34] Equivalent to get doc env([], [], [], Opts). get doc env(App, Packages, Modules, Options::proplist()) edoc env() [page 34] Creates an environment data structure used by parts of EDoc for generating references, etc. get first sentence(Es) [page 35] is name(Cs) [page 35]
term() term() term()

is relative uri(Cs) [page 35] is space(Cs) [page 35]


term()

join uri(Base, Path) [page 35] lines(Cs) [page 35]


term()

term()

parse contact(S, L) - term() [page 35] EDoc contact information parsing. parse expr(S, L) - term() [page 35] EDoc Erlang expression parsing. read info file(Dir) [page 35]
term()

run doclet(Fun, Opts) - term() [page 35] See edoc:run/3 for a description of the doclet option. run layout(Fun, Opts) - term() [page 35] See edoc:layout/2 for a description of the layout option. segment(Es, N) [page 35] simplify path(P) [page 35]
term() term()

20

EDoc Application

EDoc Reference Manual

split at(Cs, K) [page 35]

term() term() term() term()

split at space(Cs) [page 36] split at stop(Cs) [page 36] strip space(Cs) [page 36] timestr(X1) [page 36] to label(Cs) [page 36] transpose(Xss) [page 36]

term() term() term() term()

try subdir(Dir, Subdir) [page 36] unique(Xs) [page 36]


term() term()

uri get(Path) [page 36]

write file(Text::deep string(), Dir::filename() (see module edoc), Name::filename() (see module edoc)) - ok [page 36] Write the given Text to the le named by Name in directory Dir. write file(Text::deep string(), Dir::filename() (see module edoc), Name::filename() (see module edoc), Package::atom() | string()) ok [page 36] Like write le/3, but adds path components to the target directory corresponding to the specied package. write info file(App, Packages, Modules, Dir) [page 36]
term()

edoc run
The following functions are exported:

application(Args::[string()]) - none() [page 37] Calls edoc:application/3 with the corresponding arguments. file(Args::[string()]) - none() [page 37] Calls edoc:le/2 with the corresponding arguments. files(Args::[string()]) - none() [page 37] Calls edoc:les/2 with the corresponding arguments. packages(Args::[string()]) - none() [page 38] Calls edoc:application/2 with the corresponding arguments.

EDoc Application

21

edoc

EDoc Reference Manual

edoc
Erlang Module

EDoc - the Erlang program documentation generator. This module provides the main user interface to EDoc.

EDoc User Manual [page 1] Running EDoc [page 2]

DATA TYPES
edoc module() The EDoc documentation data for a module, expressed as an XML document in [XMerL] format. See the le edoc.dtd1 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, []) [page 22]. application(Application::atom(), Options::proplist()) ok

Run EDoc on an application in its default app-directory. See application/3 [page 22] for details. See also: application/1 [page 22]. application(Application::atom(), Dir::filename(), Options::proplist()) ok

Run EDoc on an application located in the specied directory. Tries to automatically set up good defaults. Unless the user species 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.
1 URL:

../../priv/edoc.dtd

22

EDoc Application

EDoc Reference Manual

edoc

The subpackages [page 26] option is turned on. All found source les will be processed. The include subdirectory is automatically added to the include path. (Only important if preprocessing [page 25] is turned on.)
See run/3 [page 26] for details, including options. See also: application/2 [page 22]. file(Name::filename()) ok

This function is deprecated: See le/2 [page 23] for details. Equivalent to le(Name, []) [page 23]. 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 [page 22], packages/2 [page 25] and les/2 [page 23]. Reads a source code le and outputs formatted documentation to a corresponding le. Options: dir, filename() Species the output directory for the created le. (By default, the output is written to the directory of the source le.) source suffix, string() default value is ".erl". file suffix, string() ".html". Species the expected sufx of the input le. The Species the sufx for the created le. The default value is

See get doc/2 [page 24] and layout/2 [page 24] for further options. For running EDoc from a Makele or similar, see edoc run:le/1 [page 37]. See also: read/2 [page 25]. files(Files::[filename() | package(), [filename()] ]) ok

Equivalent to packages(Packages, []) [page 25]. files(Files::[filename() | package(), [filename()] ], Options::proplist()) ok

Runs EDoc on a given set of source les. See run/3 [page 26] for details, including options. get doc(File::filename()) ModuleName, edoc module()

Equivalent to get doc(File, []) [page 24]. get doc(File::filename(), Options::proplist()) Types: ModuleName, edoc module()

ModuleName = atom()

EDoc Application

23

edoc

EDoc Reference Manual Reads a source code le and extracts EDoc documentation data. Note that without an environment parameter (see get doc/3 [page 24]), hypertext links may not be correct. Options: def, Macros Macros = Macro | [Macro] Macro = Name::atom(), Text::string() Species a set of EDoc macro denitions. See Inline macro expansion [page 10] for details. hidden, bool() If the value is true, documentation of hidden functions will also be included. The default value is false. private, bool() If the value is true, documentation of private functions will also be included. The default value is false. todo, bool() 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 [page 25], read comments/2 [page 25] and edoc lib:get doc env/4 [page 35] for further options. See also: get doc/3 [page 24], layout/2 [page 24], read/2 [page 25], run/3 [page 26], edoc extract:source/5 [page 32].

get doc(File::filename(), Env::edoc env() (see module edoc lib), Options::proplist()) ModuleName, edoc module() Types:

ModuleName = atom()
Like get doc/2 [page 24], but for a given environment parameter. Env is an environment created by edoc lib:get doc env/4 [page 35]. layout(Doc::edoc module()) string()

Equivalent to layout(Doc, []) [page 24]. 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() Species a callback module to be used for formatting. The module must export a function module(Doc, Options). The default callback module is edoc layout [page 33]; see edoc layout:module/2 [page 33] for layout-specic options. See also: le/2 [page 23], layout/1 [page 24], read/2 [page 25], run/3 [page 26]. packages(Packages::[package()]) ok

Equivalent to packages(Packages, []) [page 25]. packages(Packages::[package()], Options::proplist()) ok

24

EDoc Application

EDoc Reference Manual

edoc

Runs EDoc on a set of packages. The source path option is used to locate the les; see run/3 [page 26] for details, including options. This function automatically appends the current directory to the source path. read(File::filename()) string()

Equivalent to read(File, []) [page 25]. read(File::filename(), Options::proplist()) string()

Reads and processes a source le and returns the resulting EDoc-text as a string. See get doc/2 [page 24] and layout/2 [page 24] for options. See also: le/2 [page 23]. read comments(File) [comment()]

Equivalent to read comments(File, []) [page 25]. read comments(File::filename(), Options::proplist()) Types: [comment()]

Line, Column, Indentation, Text Line = integer() Column = integer() Indentation = integer() Text = [string()]

Extracts comments from an Erlang source code le. See the module [erl comment scan(3)] for details on the representation of comments. Currently, no options are avaliable. read source(Name::File) [syntaxTree()]

Equivalent to read source(File, []) [page 25]. read source(File::filename(), Options::proplist()) Options: preprocess, bool() If the value is true, the source le 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 le contains too exotic denitions or uses of macros, it will not be possible to read it without preprocessing. Note: comments in included les will not be available to EDoc, even with this option enabled. includes, Path::[string()] Species a list of directory names to be searched for include les, 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 le is always automatically appended to the search path. [syntaxTree()]

Reads an Erlang source le and returns the list of source code form syntax trees.

EDoc Application

25

edoc

EDoc Reference Manual macros, [ atom(), term() ] Species a list of pre-dened Erlang preprocessor (epp) macro denitions, used if the preprocess option is turned on. The default value is the empty list. See also: [erl syntax(3)], get doc/2 [page 24].

run(Packages::[package()], Files::[filename() | Options::proplist()) - ok

package(), [filename()] ],

Runs EDoc on a given set of source les and/or packages. Note that the doclet plugin module has its own particular options; see the doclet option below. Also see layout/2 [page 24] for layout-related options, and get doc/2 [page 24] for options related to reading source les. Options: app default, string() Species the default base URI for unknown applications.

application, App::atom() Species that the generated documentation describes the application App. This mainly affects generated references. dir, filename() Species the target directory for the generated documentation. doc path, [string()] Species 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() Species 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 [page 28]; see edoc doclet:run/2 [page 28] for doclet-specic options. exclude packages, [package()] Lists packages to be excluded from the documentation. Typically used in conjunction with the subpackages option. file suffix, string() Species the sufx used for output les. The default value is ".html". Note that this also affects generated references. new, bool() If the value is true, any existing edoc-info le in the target directory will be ignored and overwritten. The default value is false. packages, bool() If the value is true, it it assumed that packages (module namespaces) are being used, and that the source code directory structure reects 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()] source code for packages. source suffix, string() value is ".erl". Species a list of le system paths used to locate the Species the expected sufx of input les. The default

26

EDoc Application

EDoc Reference Manual

edoc

subpackages, bool() If the value is true, all subpackages of specied 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 les are found by recursively searching for source code les 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 [page 22], les/2 [page 23], packages/2 [page 25].

EDoc Application

27

edoc doclet

EDoc Reference Manual

edoc doclet
Erlang Module

Standard doclet module for EDoc.

DATA TYPES

doclet gen() = #doclet gen sources=[string()], app=no app() | atom(), packages=[atom()], mod doclet toc() = #doclet gen paths=[string()], indir=string() edoc context() = #context dir=string(), env=edoc env() (see module edoc lib), opts=[term()] no app() A value used to mark absence of an Erlang application context. Use the macro NO APP dened in edoc doclet.hrl2 to produce this value.

Exports
run(Command::doclet gen() | doclet toc(), Ctxt::edoc context()) 3

ok

Main doclet entry point. See the le edoc doclet.hrl for the data structures used for passing parameters. Also see edoc:layout/2 [page 24] for layout-related options, and edoc:get doc/2 [page 24] for options related to reading source les. Options: file suffix, string() is ".html". Species the sufx used for output les. The default value

hidden, bool() If the value is true, documentation of hidden modules and functions will also be included. The default value is false. overview, edoc:filename() Species the name of the overview-le. By default, this doclet looks for a le "overview.edoc" in the target directory. private, bool() If the value is true, documentation of private modules and functions will also be included. The default value is false. stylesheet, string() Species the URI used for referencing the stylesheet. The default value is "stylesheet.css". If an empty string is specied, no stylesheet reference will be generated.
2 URL: 3 URL:

../../include/edoc doclet.hrl ../../include/edoc doclet.hrl

28

EDoc Application

EDoc Reference Manual

edoc doclet

stylesheet file, edoc:filename() Species the name of the stylesheet le. By default, this doclet uses the le "stylesheet.css" in the priv subdirectory of the EDoc installation directory. The named le will be copied to the target directory. title, string() Species the title of the overview-page.

See also
edoc [page 22]

EDoc Application

29

edoc extract

EDoc Reference Manual

edoc extract
Erlang Module

EDoc documentation extraction.

DATA TYPES
edoc env() = edoc env() (see module edoc lib) filename() = filename() (see module file)

Exports
file(File::filename(), Context, Env::edoc env(), Options::proplist()) error, Reason Types: ok, Tags |

Context = overview | package Tags = [term()] Reason = term()


Reads a text le and returns the list of tags in the le. Any lines of text before the rst tag are ignored. Env is an environment created by edoc lib:get doc env/4 [page 35]. Upon error, Reason is an atom returned from the call to [le:read le/1]. See text/4 [page 32] for options. header(File::filename(), Env::edoc env(), Options::proplist()) error, Reason Types: ok, Tags |

Tags = [term()] Reason = term()


Similar to header/5 [page 31], but reads the syntax tree and the comments from the specied le. See also: header/4 [page 31], edoc:read comments/2 [page 25], edoc:read source/2 [page 25]. header(Forms, File::filename(), Env::edoc env(), Options::proplist()) error, Reason Types: ok, Tags |

Forms = syntaxTree() | [syntaxTree()]

30

EDoc Application

EDoc Reference Manual

edoc extract

Tags = [term()] Reason = term()


Extracts EDoc documentation from commented header le syntax trees. Similar to source/5 [page 32], but ignores any documentation that occurs before a module declaration or a function denition. (Warning messages are printed if content may be ignored.) Env is assumed to already be set up with a suitable module context. See also: [erl recomment(3)], header/5 [page 31]. header(Forms, Comments::[comment()], File::filename(), Env::edoc env(), ok, Tags | error, Reason Options::proplist()) Types:

Forms = syntaxTree() | [syntaxTree()] Tags = [term()] Reason = term()


Similar to header/4 [page 31], but rst inserts the given comments in the syntax trees. The syntax trees must contain valid position information. (Cf. edoc:read comments/2 [page 25].) See also: [erl recomment(3)], header/3 [page 30], header/4 [page 31]. source(File::filename(), Env::edoc env(), Options::proplist()) edoc module() Types: ModuleName,

ModuleName = atom() term()


Like source/5 [page 32], but reads the syntax tree and the comments from the specied le. See also: source/4 [page 31], edoc:read comments/2 [page 25], edoc:read source/2 [page 25]. source(Forms, File::filename(), Env::edoc env(), Options::proplist()) edoc module() Types: ModuleName,

Forms = syntaxTree() | [syntaxTree()] ModuleName = atom() edoc module() (see module edoc)
Extracts EDoc documentation from commented source code syntax trees. The given Forms must be a single syntax tree of type form list, or a list of syntax trees representing program forms (cf. edoc:read source/2 [page 25]. Env is an environment created by edoc lib:get doc env/4 [page 35]. The File argument is used for error reporting and output le name generation only. See edoc:get doc/2 [page 24] for descriptions of the def, hidden, private, and todo options. See also: [erl recomment(3)], source/5 [page 32], edoc:read comments/2 [page 25], edoc:read source/2 [page 25].

EDoc Application

31

edoc extract

EDoc Reference Manual

source(Forms, Comments::[comment()], File::filename(), Env::edoc env(), ModuleName, edoc module() Options::proplist()) Types:

Forms = syntaxTree() | [syntaxTree()] Line, Column, Indentation, Text Line = integer() Column = integer() Indentation = integer() Text = [string()] ModuleName = atom()

Like source/4 [page 31], but rst inserts the given comments in the syntax trees. The syntax trees must contain valid position information. (Cf. edoc:read comments/2 [page 25].) See also: [erl recomment(3)], source/3 [page 31], source/4 [page 31], edoc:read comments/2 [page 25], edoc:read source/2 [page 25]. text(Text::string(), Context, Env::edoc env(), Options::proplist()) Types: Tags

Context = overview | package Tags = [term()]


Returns the list of tags in the text. Any lines of text before the rst tag are ignored. Env is an environment created by edoc lib:get doc env/4 [page 35]. See source/4 [page 31] for a description of the def option.

See also
edoc [page 22]

32

EDoc Application

EDoc Reference Manual

edoc layout

edoc layout
Erlang Module

The standard HTML layout module for EDoc. See the edoc [page 22] module for details on usage.

Exports
module(Element, Options) term()

The layout function. Options to the standard layout: index columns, integer() Species the number of column pairs used for the function index tables. The default value is 1. stylesheet, string() Species the URI used for referencing the stylesheet. The default value is "stylesheet.css". If an empty string is specied, no stylesheet reference will be generated. sort functions, bool() If true, the detailed function descriptions are listed by name, otherwise they are listed in the order of occurrence in the source le. The default value is true. xml export, Module::atom() Species an [xmerl] callback module to be used for exporting the documentation. See [xmerl:export simple/3] for details. See also: edoc:layout/2 [page 24]. overview(E, Options) package(E, Options) type(E) term() term() term()

See also
edoc [page 22]

EDoc Application

33

edoc lib

EDoc Reference Manual

edoc lib
Erlang Module

Utility functions for EDoc.

DATA TYPES
edoc env() Environment information needed by EDoc for generating references. The data representation is not documented. info() = #info name=string(), mail=string(), uri=string()

Exports
copy file(From, To) count(X, Xs) datestr(X1) term() term() term() term()

escape uri(Cs) filename(T) -

term() term() term() term() term()

find doc dirs() -

find file(Ps, Pkg, Name) find sources(Path, Opts) -

find sources(Path, Pkg, Opts) -

See edoc:run/3 [page 26] for a description of the options subpackages, source suffix and exclude packages. get doc env(Options::proplist()) edoc env()

Equivalent to get doc env([], [], [], Opts) [page 35]. get doc env(App, Packages, Modules, Options::proplist()) edoc env()

34

EDoc Application

EDoc Reference Manual Types:

edoc lib

App = [] | atom() Packages = [atom()] Modules = [atom()] term()


Creates an environment data structure used by parts of EDoc for generating references, etc. See edoc:run/3 [page 26] for a description of the options file suffix, app default and doc path. See also: edoc:get doc/3 [page 24], edoc extract:source/4 [page 31]. get first sentence(Es) is name(Cs) term() term() term()

is relative uri(Cs) is space(Cs) term()

join uri(Base, Path) lines(Cs) term()

term()

parse contact(S, L) -

term()

EDoc contact information parsing. This is the type of the content in e.g. @author [page 5] tags. parse expr(S, L) term()

EDoc Erlang expression parsing. For parsing things like the content of @equiv [page 6] tags, and strings denoting le names, e.g. in @headerle. Also used by edoc run [page 37]. read info file(Dir) run doclet(Fun, Opts) term() term()

See edoc:run/3 [page 26] for a description of the doclet option. run layout(Fun, Opts) term()

See edoc:layout/2 [page 24] for a description of the layout option. segment(Es, N) simplify path(P) split at(Cs, K) term() term() term()

EDoc Application

35

edoc lib split at space(Cs) split at stop(Cs) strip space(Cs) timestr(X1) to label(Cs) transpose(Xss) term() term() term()

EDoc Reference Manual

term() term() term() term()

try subdir(Dir, Subdir) unique(Xs) term() term()

uri get(Path) -

write file(Text::deep string(), Dir::filename() (see module edoc), Name::filename() (see module edoc)) - ok Write the given Text to the le named by Name in directory Dir. If the target directory does not exist, it will be created. write file(Text::deep string(), Dir::filename() (see module edoc), Name::filename() (see module edoc), Package::atom() | string()) - ok Like write le/3 [page 36], but adds path components to the target directory corresponding to the specied package. write info file(App, Packages, Modules, Dir) term()

See also
edoc [page 22]

36

EDoc Application

EDoc Reference Manual

edoc run

edoc run
Erlang Module

Interface for calling EDoc from Erlang startup options. The following is an example of typical usage in a Makele: docs: erl -noshell -run edoc run application "$(APP NAME)" \n (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 terminate. 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 [page 22] 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 rst case edoc:application/1 [page 22] is called instead; in the second case, edoc:application/2 [page 22] 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 [page 37], packages/1 [page 38] and les/1 [page 38]. Calls edoc:le/2 [page 23] 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 rst case, an empty list of options is passed to edoc:le/2 [page 23]. The following is an example of typical usage in a Makele: $(DOCDIR)/%.html:%.erl erl -noshell -run edoc run file "$ " [ dir,"$(DOCDIR)" ] \n 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()

EDoc Application

37

edoc run

EDoc Reference Manual Calls edoc:les/2 [page 23] 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 rst case, edoc:les/1 [page 23] 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 [page 22] 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 rst case edoc:application/1 [page 22] 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 [page 22]

38

EDoc Application

List of Tables
1.1 reference syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

EDoc Application

39

List of Tables

40

EDoc Application

Index of Modules and Functions


Modules are typed in this way . Functions are typed in this way. application/1 edoc , 22 edoc run , 37 copy_file/2 edoc lib , 34 count/2 edoc lib , 34 datestr/1 edoc lib , 34 copy_file/2, 34 count/2, 34 datestr/1, 34 escape_uri/1, 34 filename/1, 34 find_doc_dirs/0, 34 find_file/3, 34 find_sources/2, 34 find_sources/3, 34 get_doc_env/1, 34 get_doc_env/4, 34 get_first_sentence/1, 35 is_name/1, 35 is_relative_uri/1, 35 is_space/1, 35 join_uri/2, 35 lines/1, 35 parse_contact/2, 35 parse_expr/2, 35 read_info_file/1, 35 run_doclet/2, 35 run_layout/2, 35 segment/2, 35 simplify_path/1, 35 split_at/2, 35 split_at_space/1, 36 split_at_stop/1, 36 strip_space/1, 36 timestr/1, 36 to_label/1, 36 transpose/1, 36 try_subdir/2, 36 unique/1, 36 uri_get/1, 36 write_file/1, 36 write_info_file/4, 36

edoc application/1, 22 file/1, 23 files/1, 23 get_doc/1, 23, 24 layout/1, 24 packages/1, 24 read/1, 25 read_comments/1, 25 read_source/1, 25 run/1, 26 edoc doclet run/1, 28 edoc extract file/1, 30 header/1, 30 header/2, 30, 31 source/1, 31 source/2, 31, 32 text/1, 32 edoc layout module/2, 33 overview/2, 33 package/2, 33 type/1, 33 edoc lib

edoc run application/1, 37 file/1, 37 files/1, 37

EDoc Application

41

Index of Modules and Functions packages/1, 38 escape_uri/1 edoc lib , 34 file/1 edoc , 23 edoc extract , 30 edoc run , 37 filename/1 edoc lib , 34 files/1 edoc , 23 edoc run , 37 find_doc_dirs/0 edoc lib , 34 find_file/3 edoc lib , 34 find_sources/2 edoc lib , 34 find_sources/3 edoc lib , 34 get_doc/1 edoc , 23, 24 get_doc_env/1 edoc lib , 34 get_doc_env/4 edoc lib , 34 get_first_sentence/1 edoc lib , 35 header/1 edoc extract , 30 header/2 edoc extract , 30, 31 is_name/1 edoc lib , 35 is_relative_uri/1 edoc lib , 35 is_space/1 edoc lib , 35 join_uri/2 edoc lib , 35 layout/1 edoc , 24 lines/1 edoc lib , 35 module/2 edoc layout , 33 overview/2 edoc layout , 33 package/2 edoc layout , 33 packages/1 edoc , 24 edoc run , 38 parse_contact/2 edoc lib , 35 parse_expr/2 edoc lib , 35 read/1 edoc , 25 read_comments/1 edoc , 25 read_info_file/1 edoc lib , 35 read_source/1 edoc , 25 run/1 edoc , 26 edoc doclet , 28 run_doclet/2 edoc lib , 35 run_layout/2 edoc lib , 35 segment/2 edoc lib , 35 simplify_path/1 edoc lib , 35 source/1 edoc extract , 31 source/2 edoc extract , 31, 32

42

EDoc Application

Index of Modules and Functions split_at/2 edoc lib , 35 split_at_space/1 edoc lib , 36 split_at_stop/1 edoc lib , 36 strip_space/1 edoc lib , 36 text/1 edoc extract , 32 timestr/1 edoc lib , 36 to_label/1 edoc lib , 36 transpose/1 edoc lib , 36 try_subdir/2 edoc lib , 36 type/1 edoc layout , 33 unique/1 edoc lib , 36 uri_get/1 edoc lib , 36 write_file/1 edoc lib , 36 write_info_file/4 edoc lib , 36

EDoc Application

43

Index of Modules and Functions

44

EDoc Application

Anda mungkin juga menyukai