Copyright © 2006-2015 Ericsson AB. All Rights Reserved
Contents
1. type See the type generic tag for details Placing a t ype tag by a function definition may be convenient but does not affect where the description is placed in the generated documentation 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 Example Scope Function Arity Within module Module Function Arity Global Type Within module Module Type Global Application Global Application Module Global Application Module Function Arity Pune Global Application Module Type edoc edoc_module Global Table 1 1 reference syntax EDoc will resolve references using the information it finds in edoc info files at the locations specified with the doc path option EDoc will automatically and somewhat intelligently try to find any local edoc info files 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 file this allows documentation to be built incrementally Use the new option to ignore any old info file 8 Ericsson AB All Rights Reserved EDoc 1 1 Welcome to EDoc Note that if the name of a module function or datatype is explicitly qualified with an application as in edoc edoc ru2. x ERLANG EDoc Copyright 2006 2015 Ericsson AB All Rights Reserved EDoc 0 7 17 December 15 2015 Copyright 2006 2015 Ericsson AB AII Rights Reserved Licensed under the Apache License Version 2 0 the License you may not use this file except in compliance with the License You may obtain a copy of the License at http www apache org licenses LICENSE 2 0 Unless required by applicable law or agreed to in writing software distributed under the License is distributed on an AS IS BASIS WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND either express or implied See the License for the specific language governing permissions and limitations under the License Ericsson AB All Rights Reserved December 15 2015 Ericsson AB All Rights Reserved EDoc 1 1 1 Welcome to EDoc 1 EDoc User s 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 e Introduction e Running EDoc e The overview page e Generic tags e Overview tags e Module tags e Function tags e Refe
3. 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 24 Ericsson AB All Rights Reserved EDoc edoc doclet edoc doclet Erlang module Standard doclet module for EDoc DATA TYPES doclet gen doclet_gen sources string app no_app atom modules atom doclet toc doclet_gen paths string indir string edoc_context opts term no app context dir string env edoc_env see module edoc lib A value used to mark absence of an Erlang application context Use the macro NO APP defined in edoc doclet hrl to produce this value Exports run Command doclet gen doclet toc Ctxt edoc context ok Main doclet entry point See the file edoc doclet hrl for the data structures used for passing parameters Also see edoc layout 2 for layout related options and edoc get doc 2 for options related to reading source files Options file suffix string Specifies the suffix used for output files The default value is htm1 hidden boolean If the value is true documentation of hidden modules and functions will also be included The default value is false overview edoc filename Specifies the name
4. FunType fun FunType fun UnionTypes j Atom Fields 50 pepe sp UnionType UnionType UnionType BinType TypeName UnionTypes ModuleName TypeName UnionTypes AppName ModuleName TypeName UnionTypes Field Fields Fields Atom UnionList lt lt gt gt lt lt BaseType gt gt lt lt UnitType gt gt Tegn BaseType n UnitType gt gt Integer wo onu non mk Integer Variable Atom Atom ModuleName Atom Atom Def DefList Def DefList Def TypeVariable UnionList TypeName 1 1 Welcome to EDoc TypeVariables UnionType TypeVariable TypeVariables n TypeVariable TypeVariables Table 1 2 specification syntax grammar Examples spec my_function X integer gt integer doc Creates ge spec my function X integer gt integer ge spec X integer gt integer ge spec sqrt float float ge spec pair S T S T spec append List List gt List List term ge ge oe Qspec append A List B List List List Item Item term de ge ge oe ge ge spec open File filename FileDescriptor where filename string atom FileDescriptor term de ge ge ge oe ge ge oe ge spec cl
5. href Concerning Hobbits gt Concerning Hobbits lt a gt 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 using the URL both for the destination and the label of the reference equivalent to writing lt a href http www w3c org tt http www w3c org tt a This 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 Qtodo see todo tags for further details 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 10 Ericsson AB All Rights Reserved EDoc 1 1 Welcome to EDoc yn A character sequence or will be expanded to lt code gt lt code gt where all occurrences of the special XML characters and amp and for completeness also gt in the quoted text have been escaped to amp 1t amp amp and amp gt respectively All whitespace is stripped from the beginning and end of the quoted text yt Double back quotes can be used to quote text containi
6. of the overview file By default this doclet looks for a file overview edoc in the target directory private boolean If the value is true documentation of private modules and functions will also be included The default value is false stylesheet string Specifies the URI used for referencing the stylesheet The default value is Stylesheet css If an empty string is specified no stylesheet reference will be generated stylesheet file edoc filename Specifies the name of the stylesheet file By default this doclet uses the file stylesheet css inthe priv subdirectory of the EDoc installation directory The named file will be copied to the target directory title string Specifies the title of the overview page Ericsson AB All Rights Reserved EDoc 25 edoc doclet See also edoc 26 Ericsson AB All Rights Reserved EDoc edoc extract edoc extract Erlang module EDoc documentation extraction DATA TYPES doc env edoc env see module edoc lib filename filename s module file proplist property see module proplists aps syntaxTree see module erl syntax t 1 Some docs of t 0 Further docs of t 0 The same thing using type type t t10 Some docs of t 0 Further docs of t 0 Exports file File filename Context Env edoc env Options proplist ok Tags error Reason Types Context overview Tags t
7. overview file this is the overview doc file for the application frob author R J Hacker lt rjh acme com gt 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 Ericsson AB All Rights Reserved EDoc 3 1 1 Welcome to EDoc ifdef DEBUG doc Doo endif clear 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 first doc tag really belongs to since preprocessing strips away all such information docfile Reads a plain documentation file on the same format as an overview file see The overview page for details and uses the tags in that file as if they had been written in place of the docfile tag The content is the name of the file to be read leading and trailing whitespace is ignored See also headerfile end The text following this tag is alw
8. the end of the file in the footer 1 1 3 Running EDoc The following are the main functions for running EDoc e edoc application 2 Creates documentation for a typical Erlang application e edoc files 2 Creates documentation for a specified set of source files e edoc run 2 General interface function the common back end for the above functions Options are documented here Note that the function edoc file 2 belongs to the old deprecated interface from EDoc version 0 1 and should not be used 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 finer details to the documentation for individual modules By default the overview page is generated from the file overview edoc in the target directory typically this is the doc subdirectory of the application directory see edoc_doclet for details The format of the overview file is the same as for EDoc documentation comments see Introduction except that the lines do not have leading characters Furthermore all lines before the first tag line are ignored and can be used as a comment All tags in the overview file such as doc version etc refer to the application as a whole see Overview tags for details Here is an example of the contents of an
9. the todo option is turned on see edoc get doc 2 type Documents an abstract data type or type alias The content consists of a type declaration or definition 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 specifications for syntax and examples All data type descriptions are placed in a separate section of the documentation regardless of where the tags occur Instead of specifying the complete type alias in an EDoc documentation comment type definitions from the actual Erlang code can be re used for documentation See Type specifications for examples 1 1 6 Overview tags The following tags can be used in an overview file author See the author module tag for details copyright See the copyright module tag for details doc See the doc module tag for details reference See the reference module tag for details see See the see module tag for details since See the since module tag for details title Specifies a title for the overview page This tag can only be used in an overview file The content can be arbitrary text version See the version module tag for details 1 1 7 Module tags The following tags can be used before a module declaration author Specifies the name of an author along with contact information An e mail address can be given
10. anual Running EDoc DATA TYPES comment Line Column Indentation Text Line integer Column integer e Indentation integer e 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 s module kernel file proplist term syntaxTree syntaxTree see module syntax_tools erl_syntax Exports application Application atom gt ok Equivalent to application Application application Application atom Options proplist gt 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 gt ok Run EDoc on an application located in the specified directory Tries to automatically set up good defaults Unless the user specifies otherwise e The doc subdirectory will be used as the target directory if it exists otherwise the application directory is used e 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 e The include subdirectory is automatically added to the include path Only important if preprocessing is turned on See run 2 for details including
11. ays ignored Use this to mark the end of the previous tag when necessary as e g in 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 docfile tag but reads a file containing Erlang source code generally this should be a header file with the extension hr1 If the file turns out to contain one or more function definitions or a module declaration all tags that occur above the last such definition or module declaration are ignored and EDoc will print a warning This tag allows you to write documentation in a header file and insert it at a specific place in the documentation even if the header file is used i e included by several modules The includes option can be used to specify a search path see edoc read_source 2 t odo or TODO Attaches a To Do note to a function module 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 ww ietf org rfc rfc2549 txt gt RFC 2549 lt a gt These tags can also be written as TODO e g 4 Ericsson AB All Rights Reserved EDoc 1 1 Welcome to EDoc TODO call your mother see Wiki notation for more information To Do notes are normally not shown unless
12. 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 t rue documentation of hidden functions will also be included The default value is false Ericsson AB All Rights Reserved EDoc 21 edoc 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 t odo or TODO tags will be included in the documentation The default value is false See read_source 2 read_comments 2 and edoc_lib get_doc_env 3 for further options See also get_doc 3 layout 2 read 2 run 2 edoc_extract source 5 get doc File filename Env edoc env see module edoc lib Options proplist gt 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 3 layout Doc edoc module gt 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 layou
13. der 4 but first inserts the given comments in the syntax trees The syntax trees must contain valid position information Cf edoc read_comments 2 See also erl_recomment 3 header 3 header 4 source File filename Env edoc env Options proplist ModuleName edoc module see module edoc Types ModuleName atom term Like source 5 but reads the syntax tree and the comments from the specified file See also source 4 edoc read_comments 2 edoc read_source 2 source Forms File filename Env edoc env Options proplist gt ModuleName edoc module see module edoc Types Forms syntaxTree syntaxTree ModuleName atom 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 Env is an environment created by edoc_lib get_doc_env 3 The File argument is used for error reporting and output file name generation only See edoc get_doc 2 for descriptions of the def hidden private and todo options See also erl_recomment 3 source 5 edoc read comments 2 edoc read_source 2 source Forms Comments comment see module edoc File filename Env edoc env Options proplist gt ModuleName edoc module see module edoc Types Forms syntaxTree syntaxTree ModuleName atom Like source 4 b
14. e as Hr Min Sec e g 22 27 26 type type expression Formats a type expression within lt code gt lt code gt 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 version Intended for use in version tags Defaults to a timestamp using date and time Typically this macro is redefined by the user when an official 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 Expands to Example 12 Ericsson AB All Rights Reserved EDoc 1 1 Welcome to EDoc doc foo Key Value ee 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 P d ge oe de oe 1 1 13 Type specifications Function specifications Note Although the syntax described in the follo
15. e module using well formed XHTML text The first sentence is used as a summary see the doc function tag for details For example doc This is a lt em gt very lt em gt 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 Specifies 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 lt em gt Interesting Times lt em gt 6 Ericsson AB All Rights Reserved EDoc 1 1 Welcome to EDoc Victor Gollancz Ltd 1994 reference See a href www google com gt Google lt a gt for ore information je oe 320 see See the see function tag for details since Specifies when the module was introduced with respect to the application release or distribution it is part of The content can be arbitrary text version Specifies the module version The content can be arbitrary text 1 1 8 Function tags The following tags ca
16. efile 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 I 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 32 Ericsson AB All Rights Reserved EDoc edoc run See also edoc Ericsson AB All Rights Reserved EDoc 33
17. erm Reason term Reads a text file and returns the list of tags in the file Any lines of text before the first tag are ignored Env is an environment created by edoc lib get doc env 3 Upon error Reason is an atom returned from the call to file read file 1 or the atom invalid unicode See text 4 for options header File filename Env edoc env Options proplist ok Tags error Reason Types Tags term Reason term Similar to header 5 but reads the syntax tree and the comments from the specified file See also header 4 edoc read_comments 2 edoc read_source 2 header Forms File filename Env edoc env Options proplist gt ok Tags error Reason Types Forms syntaxTree syntaxTree Tags term Reason term Extracts EDoc documentation from commented header file syntax trees Similar to source 5 but ignores any documentation that occurs before a module declaration or a function definition Warning messages are printed if content may be ignored Env is assumed to already be set up with a suitable module context Ericsson AB All Rights Reserved EDoc 27 edoc extract See also erl recomment 3 header 5 header Forms Comments comment see module edoc File filename Env edoc env Options proplist gt ok Tags error Reason Types Forms syntaxTree syntaxTree Tags term Reason term Similar to hea
18. et 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 Ericsson AB All Rights Reserved EDoc 23 edoc file suffix string Specifies the suffix used for output files The default value is ht m1 Note that this also affects generated references new boolean If the value is t rue any existing edoc info file in the target directory will be ignored and overwritten The default value is false source path filename Specifies a list of file system paths used to locate the source code for packages source suffix string Specifies the expected suffix of input files The default value is er1 subpackages boolean If the value is t rue all subpackages of specified packages will also be included in the documentation The default value is false no_subpackages is an alias for subpackages false Subpackage source files are found by recursively searching for source code files in subdirectories of the known
19. ion APP_NAME TU LA 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 terminate The termination signalling success or failure to the operating system is now built into these functions Exports application Args string gt 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 gt 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 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 Mak
20. me 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 first expanded in the current environment and the result is bound to the macro parameter written 82 If no argument is given 8 is bound to the empty string The macro definition is then substituted for the call and expansion continues over the resulting text Recursive macro expansions are not allowed User defined macros Users can define their own macros by using the def EDoc option see edoc file 2 and edoc get doc 2 for more information User defined macros override predefined macros Predefined macros date Expands to the current date as Month Day Year e g Dec 15 2015 link reference description This creates a hypertext link cf the see function tag 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 file 2 and link edoc file 2 lt em gt this link lt em gt creates this link module Expands to the name of the current module Only defined when a module is being processed section heading Expands to a hypertext link to the specified section heading see Headings for more information time Expands to the current tim
21. n 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 00 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 e 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 lt li gt 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 e XHTML tag and attribute names should always be lower case Attributes must be quoted asin e g a name top gt To write an element like the HTML lt br gt which has no actual content you can write either the full lt br gt lt br gt or better
22. n be used before a function definition deprecated See the deprecated module tag for details doc XHTML text describing the function The first sentence of the text is used as a quick summary this ends at the first 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 first 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 The content consists of a reference
23. ng single characters The automatic stripping of any surrounding whitespace makes it possible to write things like foo bar wey To quote text containing verbatim explicit lt code gt markup or similar must be used A character sequence will be expanded to lt pre gt lt CDATA gt lt pre gt which disables all XML markup within the quoted text and displays the result in fixed 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 y To produce a single character in XML without beginning a new quote you can write the and the You can of course also use the XML character entity amp x60 no space between Examples ge oe 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 CC F X gt 9595 case X of 9596 x 9595 end doc or in the following 2 gt gt 9685 g X 9595 fun end 3696 1 1 12 Macro expansion Before the content of a tag is parsed the text undergoes macro expansion The syntax for macro calls is or name name argument Ericsson AB All Rights Reserved EDoc 11 1 1 Welco
24. none means no data type E g a function that never returns has type gt none Ericsson AB All Rights Reserved EDoc 17 1 1 Welcome to EDoc 1 1 14 Acknowledgements Since the first 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 possibility to plug in different layout engines and making EDoc understand the application directory layout Itis 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 18 Ericsson AB All Rights Reserved EDoc 1 1 Welcome to EDoc 2 Reference Manual 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 Ericsson AB All Rights Reserved EDoc 19 edoc edoc Erlang module EDoc the Erlang program documentation generator This module provides the main user interface to EDoc e EDoc User M
25. o EDoc Pre defined data types The following data types are predefined by EDoc and may not be redefined any arity atom binary bitstring bool allowed but use boolean instead boolean byte char cons deep string float function integer iodata iolist list maybe improper list mfa module nil neg integer node non neg integer nonempty improper list nonempty list nonempty maybe improper list nonempty string none number pid port pos integer reference string term timeout tuple Details e any means any Erlang data type term is simply an alias for any e atom binary float function integer pid port and reference are primitive data types of the Erlang programming language e boolean is the subset of atom consisting of the atoms t rue and false e char is the subset of integer representing Unicode character codes hex 000000 10FFFF e tuple isthe set of all tuples e list T is just an alias for T list is an alias for list any ie any e nil isan alias for the empty list e cons H T is the list constructor This is usually not used directly It is possible to recursively define list T nil cons T list T e string isan alias for char e deep_string is recursively defined as char deep_string e
26. 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 lt b gt EDoc lt b gt If no label text is specified the reference itself is used as the label since Specifies in what version of the module the function was introduced cf the version module tag The content can be arbitrary text Ericsson AB All Rights Reserved EDoc 7 1 1 Welcome to EDoc spec Used to specify the function type see Type specifications for syntax details If the function name is included in the specification it must match the name in the actual code When parameter names are not given in the specification suitable names will be taken from the source code if possible and otherwise synthesized Instead of specifying the complete function type in an EDoc documentation comment specifications from the actual Erlang code can be re used for documentation See Type specifications for examples throws Specifies 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 specifications 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
27. options See also application 2 20 Ericsson AB All Rights Reserved EDoc edoc 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 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 er1 file suffix string Specifies the suffix for the created file The default value is ht m1 See get doc 2 and layout 2 for further options For running EDoc from a Makefile or similar see edoc run file l See also read 2 files Files filename ok files Files filename Options proplist ok Runs EDoc on a given set of source files See run 2 for details including options get doc File filename gt ModuleName edoc module Equivalent to get doc File get doc File filename Options proplist gt ModuleName edoc module Types ModuleName atom Reads a source
28. ose graphics window gt ok The first example shows the recommended way of specifying functions 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 specifications and may be supplied with definitions It is also possible to give definitions for named types which means that the name is simply an alias Use the t ype tag to document abstract data types If a named type is defined in another module it can be referred to as Module TypeName Note that the keyword where is optional before a list of definitions and that the definitions 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 Ericsson AB All Rights Reserved EDoc 15 1 1 Welcome to EDoc 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 fora parameter asin pair S T gt the same variable name may implicitly be used as the parameter name there is no need to write pair S S T T gt n EDoc automatically extracts possible parameter names from the source code to be used if no parameter name i
29. r 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 typesisanaliasfor report missing types false See also erl syntax 3 get doc 2 run Files filename Options proplist ok Runs EDoc on a given set of source files Note that the doclet plugin module has its own particular options see the doclet option below Also see layout 2 for layout related options and get doc 2 for options related to reading source files Options app default string Specifies the default base URI for unknown applications application App atom Specifies that the generated documentation describes the application App This mainly affects generated references dir filename Specifies the targ
30. rences Notes on XHTML e Wiki notation Macro expansion e Type specifications e Acknowledgements 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 file 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 first 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 significance the module name declaration and function definitions Other constructs are ignored e g in doc Prints the value X record foo x y z print X 2 Ericsson AB All Rights Reserved EDoc 1 1 Welcome to EDoc the doc tag is associated with the function print 1 Note that in a comment such as adoC the tag is ignored because only the first character is considered leading This allows tags to be commented out Some tags such as t ype do not need to be associated with any program construct These may be placed at
31. s given in the specification or if the specification 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 definitions Note Although the syntax described in the following can still be used for specifying types we recommend that Erlang types as described in Types and Function Specification should be added to the source code instead Erlang types will be used unless there is a type alias with the same name The following grammar see above for auxiliary definitions describes the form of the definitions that may follow a type tag TypeName TypeVariables Typedef n DefList TypeName TypeVariables UnionList DefList Table 1 3 type definition grammar For a truly abstract data type no equivalence is specified The main definition may be followed by additional local definitions Examples type my list X X A special kind of lists opaque another list X X another list is a kind of list 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 ge ge ge oe ge ge The first two examples show the recommended way of specifying types 16 Ericsson AB All Rights Reserved EDoc 1 1 Welcome t
32. stylesheet reference will be generated sort_functions boolean If t rue the detailed function descriptions are listed by name otherwise they are listed in the order of occurrence in the source file The default value is t rue xml_export Module atom Specifies an xmerl callback module to be used for exporting the documentation See xmerl export_simple 3 for details See also edoc layout 2 overview E Options term type E term See also edoc 30 Ericsson AB All Rights Reserved EDoc edoc lib 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 proplist property see module proplists Exports get doc env App Modules Options proplist edoc env Types App atom Modules atom term Creates an environment data structure used by parts of EDoc for generating references etc See edoc run 2 for a description of the options ile suffix app default and doc path See also edoc get_doc 3 edoc extract source 4 write file Text Dir Name Options term See also edoc Ericsson AB All Rights Reserved EDoc 31 edoc run edoc run Erlang module 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 applicat
33. t Module atom Specifies a callback module to be used for formatting The module must export a function module Doc Options The default callback module is edoc layout see edoc_layout module 2 for layout specific options See also file 2 layout 1 read 2 run 2 read File filename string Equivalent to read File read File 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 3 for details on the representation of comments Currently no options are avaliable read source Name File syntaxTree Equivalent to read source File 22 Ericsson AB All Rights Reserved EDoc edoc 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 t rue the source file will be read via the Erlang preprocessor epp The default value is false no preprocessisanaliasfor preprocess false Normally preprocessing is not necessary for EDoc to work but if a file contains too exotic definitions o
34. the following text This will all be part of the first 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 Ericsson AB All Rights Reserved EDoc 9 1 1 Welcome to EDoc 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 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 lt h3 gt lt a name Concerning Hobbits gt Concerning Hobbits lt a gt lt h3 gt 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 equivalent to writing lt a
35. use the XHTML abbreviated form lt br gt 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 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 specific level numbers altogether see Headings 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 specific to EDoc into proper XHTML markup This wiki http en wikipedia org wiki Wiki 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 lt em gt any XHTML markup lt em gt This is the second paragraph The above line is regarded as empty by EDoc even though it ends with a space de ge ge ge ge ge ge oe ge ge ge ge ge oe will generate
36. ut first inserts the given comments in the syntax trees The syntax trees must contain valid position information Cf edoc read_comments 2 See also erl_recomment 3 source 3 source 4 edoc read comments 2 edoc read_source 2 text Text string Context Env edoc env Options proplist Tags Types 28 Ericsson AB All Rights Reserved EDoc edoc extract Context overview Tags term Returns the list of tags in the text Any lines of text before the first tag are ignored Env is an environment created by edoc lib get doc env 3 See source 4 for a description of the def option See also edoc Ericsson AB All Rights Reserved EDoc 29 edoc layout edoc layout Erlang module The standard HTML layout module for EDoc See the edoc module for details on usage Exports module Element Options term The layout function Options to the standard layout index columns integer Specifies the number of column pairs used for the function index tables The default value is 1 pretty printer atom Specifies how types and specifications are pretty printed If the value er1 pp is specified the Erlang pretty printer the module erl pp will be used The default is to do no pretty printing which implies that lines can be very long stylesheet string Specifies the URI used for referencing the stylesheet The default value is stylesheet css If an empty string is specified no
37. wing can still be used for specifying functions we recommend that Erlang specifications as described in Types and Function Specification should be added to the source code instead This way the analyses of Dialyzer s can be utilized in the process of keeping the documentation consistent and up to date Erlang specifications will be used unless there is also a function specification a spec tag followed by a type with the same name The following grammar describes the form of the specifications following a spec tag A suffix implies that the element is optional Function types have higher precedence than union types e g atom gt atom integer is parsed as atom gt atom integer notas atom gt atom integer FunType where ee DefList FunctionName P FunType where DefList FunctionName Atom n n UnionT es n n gt FunType yp UnionType nionType UnionType UnionTypes AE XP UnionTypes UnionList Name UnionList UnionType C Name Variable Ericsson AB All Rights Reserved EDoc 13 1 1 Welcome to EDoc UnionList Type Fields Field BinType BaseType UnitType l YypeVariable TypeName ModuleName AppName DefList Def 14 Ericsson AB All Rights Reserved EDoc Type Type wiw UnionList Type UnionList TypeVariable Atom Integer Float Integer Integer
38. within lt gt 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 first nonempty string that is not within lt gt 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 first are ignored If an e mail address is given but no name the e mail string will be used also Ericsson AB All Rights Reserved EDoc 5 1 1 Welcome to EDoc for the name If no lt gt section is present but the name string contains an 8 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 lt carlsson richard gmail com gt ES http user it uu se richardc o KO author lt carlsson richard gmail com gt o 6 author carlsson richard gmail com http user it uu se richardc copyright Specifies 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 1ink reference to a replacement as in deprecated Please use the module link foo instead doc Describes th
Download Pdf Manuals
Related Search