1edoc(3) Erlang Module Definition edoc(3)
2
6 edoc - EDoc - the Erlang program documentation generator.
7
9 EDoc - the Erlang program documentation generator.
10 This module provides the main user interface to EDoc.
12 * EDoc User Manual
14 * Running EDoc
16
18 comment() = erl_comment_scan:comment():
19 edoc_module() = xmerl_scan:xmlElement():
22 The EDoc documentation data for a module, expressed as an XML docu‐
25 ment in XMerL format. See the file edoc.dtd for details.
26 entry() = #entry{name=function_name() | atom(), args=[atom() |
28 list()], line=integer(), export=boolean(), data=entry_data()}:
29 Module Entries (one per function, plus module header and footer).
32 entry_data() = term():
34 env() = #env{}:
37 Environment information needed by EDoc for generating references.
40 filename() = file:filename():
42 function_name() = {atom(), integer()}:
45 module_meta() = #module{name=[] | atom(), parameters=none | [atom()],
48 functions=ordset(function_name()), exports=ordset(function_name()),
49 attributes=ordset({atom(), term()}), records=[{atom(), [{atom(),
50 term()}]}], encoding=epp:source_encoding(), file=file:filename()}:
51 Module information.
54 ordset(T) = ordsets:ordset(T):
56 proplist() = proplists:proplist():
59 syntaxTree() = erl_syntax:syntaxTree():
62 tag() = #tag{name=atom(), line=integer(), origin=comment | code,
65 data=term(), form=undefined | erl_parse:abstract_form()}:
66 Generic tag information. #tag.form is only defined if #tag.origin
69 is code, that is the #tag{} represents a code fragment, not a doc
70 comment tag.
71
73 application(App::atom()) -> ok
74 Equivalent to application(Application, []).
76 application(App, Options) -> ok
78 Types:
80 App = atom()
82 Options = proplist()
83 Run EDoc on an application in its default app-directory. See ap‐
85 plication/3 for details.
86 See also: application/1.
88 application(App, Dir, Options) -> ok
90 Types:
92 App = atom()
94 Dir = filename()
95 Options = proplist()
96 Run EDoc on an application located in the specified directory.
98 Tries to automatically set up good defaults. Unless the user
99 specifies otherwise:
100 * The doc subdirectory will be used as the target directory,
102 if it exists; otherwise the application directory is used.
103 * The source code is assumed to be located in the src subdi‐
105 rectory, if it exists, or otherwise in the application di‐
106 rectory itself.
107 * The subpackages option is turned on. All found source files
109 will be processed.
110 * The include subdirectory is automatically added to the in‐
112 clude path. (Only important if preprocessing is turned on.)
113 See run/2 for details, including options.
115 See also: application/2.
117 file(Name::filename()) -> ok
119 This function is deprecated: See file/2 for details.
121 Equivalent to file(Name, []).
123 file(Name, Options) -> ok
125 Types:
127 Name = filename()
129 Options = proplist()
130 This function is deprecated: This is part of the old interface
132 to EDoc and is mainly kept for backwards compatibility. The pre‐
133 ferred way of generating documentation is through one of the
134 functions application/2 and files/2.
135 Reads a source code file and outputs formatted documentation to
137 a corresponding file.
138 Options:
140 {dir, filename()}:
142 Specifies the output directory for the created file. (By de‐
143 fault, the output is written to the directory of the source
144 file.)
145 {source_suffix, string()}:
147 Specifies the expected suffix of the input file. The default
148 value is ".erl".
149 {file_suffix, string()}:
151 Specifies the suffix for the created file. The default value
152 is ".html".
153 See get_doc/2 and layout/2 for further options.
155 For running EDoc from a Makefile or similar, see
157 edoc_run:file/1.
158 See also: read/2.
160 files(Files::[filename()]) -> ok
162 files(Files, Options) -> ok
164 Types:
166 Files = [filename()]
168 Options = proplist()
169 Runs EDoc on a given set of source files. See run/2 for details,
171 including options.
172 get_doc(File::filename()) -> {module(), edoc_module()}
174 Equivalent to get_doc(File, []).
176 get_doc(File, Options) -> R
178 Types:
180 File = filename()
182 Options = proplist()
183 R = {module(), edoc_module()} | {module(), edoc_module(),
184 [entry()]}
185 Reads a source code file and extracts EDoc documentation data.
187 Note that without an environment parameter (see get_doc/3), hy‐
188 pertext links may not be correct.
189 Options:
191 {def, Macros}:
193 * Macros = Macro | [Macro]
196 * Macro = {Name::atom(), Text::string() | MacroFun}
198 * MacroFun = fun((MacroArgument::string(), Line::integer(),
200 edoc_lib:edoc_env()) -> (Text::string()))
201 Specifies a set of user-defined EDoc macros. The text sub‐
203 stituted for macro calls is specified as either a string()
204 or a function(). The function is called with the macro argu‐
205 ment text, the current line number, and the current environ‐
206 ment. The fun is to return a string(). See Macro expansion
207 for details.
208 {hidden, boolean()}:
210 If the value is true, documentation of hidden functions will
211 also be included. The default value is false.
212 {private, boolean()}:
214 If the value is true, documentation of private functions
215 will also be included. The default value is false.
216 {todo, boolean()}:
218 If the value is true, To-Do notes written using @todo or
219 @TODO tags will be included in the documentation. The de‐
220 fault value is false.
221 See read_source/2, read_comments/2 and edoc_lib:get_doc_env/3
223 for further options.
224 See also: get_doc/3, layout/2, read/2, run/2, edoc_ex‐
226 tract:source/5.
227 get_doc(File, Env, Options) -> R
229 Types:
231 File = filename()
233 Env = env()
234 Options = proplist()
235 R = {module(), edoc_module()} | {module(), edoc_module(),
236 [entry()]}
237 Like get_doc/2, but for a given environment parameter. Env is an
239 environment created by edoc_lib:get_doc_env/3.
240 layout(Doc::edoc_module()) -> string()
242 Equivalent to layout(Doc, []).
244 layout(Doc, Opts) -> string()
246 Types:
248 Doc = edoc_module()
250 Opts = proplist()
251 Transforms EDoc module documentation data to text. The default
253 layout creates an HTML document.
254 Options:
256 {layout, Module::atom()}:
258 Specifies a callback module to be used for formatting. The
259 module must export a function module(Doc, Options). The de‐
260 fault callback module is edoc_layout; see edoc_layout:mod‐
261 ule/2 for layout-specific options.
262 See also: file/2, layout/1, read/2, run/2.
264 read(File::filename()) -> string()
266 Equivalent to read(File, []).
268 read(File, Opts) -> string()
270 Types:
272 File = filename()
274 Opts = proplist()
275 Reads and processes a source file and returns the resulting
277 EDoc-text as a string. See get_doc/2 and layout/2 for options.
278 See also: file/2.
280 read_comments(File::filename()) -> [comment()]
282 Equivalent to read_comments(File, []).
284 read_comments(File, Opts) -> [comment()]
286 Types:
288 File = filename()
290 Opts = proplist()
291 Extracts comments from an Erlang source code file. See the mod‐
293 ule erl_comment_scan(3) for details on the representation of
294 comments. Currently, no options are avaliable.
295 read_source(Name::filename()) -> [syntaxTree()]
297 Equivalent to read_source(File, []).
299 read_source(File, Opts) -> [syntaxTree()]
301 Types:
303 File = filename()
305 Opts = proplist()
306 Reads an Erlang source file and returns the list of "source code
308 form" syntax trees.
309 Options:
311 {preprocess, boolean()}:
313 If the value is true, the source file will be read via the
314 Erlang preprocessor (epp). The default value is false.
315 no_preprocess is an alias for {preprocess, false}.
316 Normally, preprocessing is not necessary for EDoc to work,
318 but if a file contains too exotic definitions or uses of
319 macros, it will not be possible to read it without prepro‐
320 cessing. Note: comments in included files will not be avail‐
321 able to EDoc, even with this option enabled.
322 {includes, Path::[string()]}:
324 Specifies a list of directory names to be searched for in‐
325 clude files, if the preprocess option is turned on. Also
326 used with the @headerfile tag. The default value is the
327 empty list. The directory of the source file is always auto‐
328 matically appended to the search path.
329 {macros, [{atom(), term()}]}:
331 Specifies a list of pre-defined Erlang preprocessor (epp)
332 macro definitions, used if the preprocess option is turned
333 on. The default value is the empty list.
334 {report_missing_types, boolean()}:
336 If the value is true, warnings are issued for missing types.
337 The default value is false. no_report_missing_types is an
338 alias for {report_missing_types, false}.
339 See also: erl_syntax(3), get_doc/2.
341 run(Files, Opts) -> ok
343 Types:
345 Files = [filename()]
347 Opts = proplist()
348 Runs EDoc on a given set of source files. Note that the doclet
350 plugin module has its own particular options; see the doclet op‐
351 tion below.
352 Also see layout/2 for layout-related options, and get_doc/2 for
354 options related to reading source files.
355 Options:
357 {app_default, string()}:
359 Specifies the default base URI for unknown applications.
360 {application, App::atom()}:
362 Specifies that the generated documentation describes the ap‐
363 plication App. This mainly affects generated references.
364 {dir, filename()}:
366 Specifies the target directory for the generated documenta‐
367 tion.
368 {doc_path, [string()]}:
370 Specifies a list of file system paths pointing to directo‐
371 ries that contain EDoc-generated documentation. All paths
372 for applications in the code path are automatically added.
373 {doclet, Module::atom()}:
375 Specifies a callback module to be used for creating the doc‐
376 umentation. The module must export a function run(Cmd,
377 Ctxt). The default doclet module is edoc_doclet; see
378 edoc_doclet:run/2 for doclet-specific options.
379 {file_suffix, string()}:
381 Specifies the suffix used for output files. The default
382 value is ".html". Note that this also affects generated ref‐
383 erences.
384 {new, boolean()}:
386 If the value is true, any existing edoc-info file in the
387 target directory will be ignored and overwritten. The de‐
388 fault value is false.
389 {source_path, [filename()]}:
391 Specifies a list of file system paths used to locate the
392 source code for packages.
393 {source_suffix, string()}:
395 Specifies the expected suffix of input files. The default
396 value is ".erl".
397 {subpackages, boolean()}:
399 If the value is true, all subpackages of specified packages
400 will also be included in the documentation. The default
401 value is false. no_subpackages is an alias for {subpackages,
402 false}.
403 Subpackage source files are found by recursively searching
405 for source code files in subdirectories of the known source
406 code root directories. (Also see the source_path option.)
407 Directory names must begin with a lowercase letter and con‐
408 tain only alphanumeric characters and underscore, or they
409 will be ignored. (For example, a subdirectory named test-
410 files will not be searched.)
411 See also: application/2, files/2.
413
415 Richard Carlsson <carlsson.richard@gmail.com>
416 edoc 1.0.1 edoc(3)