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 available.
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 {link_predefined_types, boolean()}:
341 If the value is true, all predefined data types will have a
342 link to the erlang module. This option is to be used when
343 generating documentation for the Erlang/OTP docs. The de‐
344 fault value is false. no_link_predefined_types is an alias
345 for {link_predefined_types, false}.
346 See also: erl_syntax(3), get_doc/2.
348 run(Files, Opts) -> ok
350 Types:
352 Files = [filename()]
354 Opts = proplist()
355 Runs EDoc on a given set of source files. Note that the doclet
357 plugin module has its own particular options; see the doclet op‐
358 tion below.
359 Also see layout/2 for layout-related options, and get_doc/2 for
361 options related to reading source files.
362 Options:
364 {app_default, string()}:
366 Specifies the default base URI for unknown applications.
367 {application, App::atom()}:
369 Specifies that the generated documentation describes the ap‐
370 plication App. This mainly affects generated references.
371 {dir, filename()}:
373 Specifies the target directory for the generated documenta‐
374 tion.
375 {doc_path, [string()]}:
377 Specifies a list of file system paths pointing to directo‐
378 ries that contain EDoc-generated documentation. All paths
379 for applications in the code path are automatically added.
380 {doclet, Module::atom()}:
382 Specifies a callback module to be used for creating the doc‐
383 umentation. The module must export a function run(Cmd,
384 Ctxt). The default doclet module is edoc_doclet; see
385 edoc_doclet:run/2 for doclet-specific options.
386 {file_suffix, string()}:
388 Specifies the suffix used for output files. The default
389 value is ".html". Note that this also affects generated ref‐
390 erences.
391 {new, boolean()}:
393 If the value is true, any existing edoc-info file in the
394 target directory will be ignored and overwritten. The de‐
395 fault value is false.
396 {source_path, [filename()]}:
398 Specifies a list of file system paths used to locate the
399 source code for packages.
400 {source_suffix, string()}:
402 Specifies the expected suffix of input files. The default
403 value is ".erl".
404 {subpackages, boolean()}:
406 If the value is true, all subpackages of specified packages
407 will also be included in the documentation. The default
408 value is false. no_subpackages is an alias for {subpackages,
409 false}.
410 Subpackage source files are found by recursively searching
412 for source code files in subdirectories of the known source
413 code root directories. (Also see the source_path option.)
414 Directory names must begin with a lowercase letter and con‐
415 tain only alphanumeric characters and underscore, or they
416 will be ignored. (For example, a subdirectory named test-
417 files will not be searched.)
418 See also: application/2, files/2.
420
422 Richard Carlsson <carlsson.richard@gmail.com>
423 edoc 1.2 edoc(3)