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() = {Line, Column, Indentation, Text}:
19 * Line = integer()
22 * Column = integer()
24 * Indentation = integer()
26 * Text = [string()]
28 edoc_module():
30 The EDoc documentation data for a module, expressed as an XML docu‐
33 ment in XMerL format. See the file edoc.dtd for details.
34 filename() = file:filename():
36 proplist() = [term()]:
39 syntaxTree() = erl_syntax:syntaxTree():
42
45 application(Application::atom()) -> ok
46 Equivalent to application(Application, []).
48 application(Application::atom(), Options::proplist()) -> ok
50 Run EDoc on an application in its default app-directory. See
52 application/3 for details.
53 See also: application/1.
55 application(Application::atom(), Dir::filename(), Options::proplist())
57 -> ok
58 Run EDoc on an application located in the specified directory.
60 Tries to automatically set up good defaults. Unless the user
61 specifies otherwise:
62 * The doc subdirectory will be used as the target directory,
64 if it exists; otherwise the application directory is used.
65 * The source code is assumed to be located in the src subdi‐
67 rectory, if it exists, or otherwise in the application
68 directory itself.
69 * The subpackages option is turned on. All found source files
71 will be processed.
72 * The include subdirectory is automatically added to the
74 include path. (Only important if preprocessing is turned
75 on.)
76 See run/2 for details, including options.
78 See also: application/2.
80 file(Name::filename()) -> ok
82 This function is deprecated: See file/2 for details.
84 Equivalent to file(Name, []).
86 file(Name::filename(), Options::proplist()) -> ok
88 This function is deprecated: This is part of the old interface
90 to EDoc and is mainly kept for backwards compatibility. The pre‐
91 ferred way of generating documentation is through one of the
92 functions application/2 and files/2.
93 Reads a source code file and outputs formatted documentation to
95 a corresponding file.
96 Options:
98 {dir, filename()}:
100 Specifies the output directory for the created file. (By
101 default, the output is written to the directory of the
102 source file.)
103 {source_suffix, string()}:
105 Specifies the expected suffix of the input file. The default
106 value is ".erl".
107 {file_suffix, string()}:
109 Specifies the suffix for the created file. The default value
110 is ".html".
111 See get_doc/2 and layout/2 for further options.
113 For running EDoc from a Makefile or similar, see
115 edoc_run:file/1.
116 See also: read/2.
118 files(Files::[filename()]) -> ok
120 files(Files::[filename()], Options::proplist()) -> ok
122 Runs EDoc on a given set of source files. See run/2 for details,
124 including options.
125 get_doc(File::filename()) -> {ModuleName, edoc_module()}
127 Equivalent to get_doc(File, []).
129 get_doc(File::filename(), Options::proplist()) -> {ModuleName,
131 edoc_module()}
132 Types:
134 ModuleName = atom()
136 Reads a source code file and extracts EDoc documentation data.
138 Note that without an environment parameter (see get_doc/3),
139 hypertext links may not be correct.
140 Options:
142 {def, Macros}:
144 * Macros = Macro | [Macro]
147 * Macro = {Name::atom(), Text::string()}
149 Specifies a set of EDoc macro definitions. See Inline macro
151 expansion for details.
152 {hidden, boolean()}:
154 If the value is true, documentation of hidden functions will
155 also be included. The default value is false.
156 {private, boolean()}:
158 If the value is true, documentation of private functions
159 will also be included. The default value is false.
160 {todo, boolean()}:
162 If the value is true, To-Do notes written using @todo or
163 @TODO tags will be included in the documentation. The
164 default value is false.
165 See read_source/2, read_comments/2 and edoc_lib:get_doc_env/3
167 for further options.
168 See also: get_doc/3, layout/2, read/2, run/2,
170 edoc_extract:source/5.
171 get_doc(File::filename(), Env::edoc_lib:edoc_env(), Options::pro‐
173 plist()) -> {ModuleName, edoc_module()}
174 Types:
176 ModuleName = atom()
178 Like get_doc/2, but for a given environment parameter. Env is an
180 environment created by edoc_lib:get_doc_env/3.
181 layout(Doc::edoc_module()) -> string()
183 Equivalent to layout(Doc, []).
185 layout(Doc::edoc_module(), Options::proplist()) -> string()
187 Transforms EDoc module documentation data to text. The default
189 layout creates an HTML document.
190 Options:
192 {layout, Module::atom()}:
194 Specifies a callback module to be used for formatting. The
195 module must export a function module(Doc, Options). The
196 default callback module is edoc_layout; see edoc_layout:mod‐
197 ule/2 for layout-specific options.
198 See also: file/2, layout/1, read/2, run/2.
200 read(File::filename()) -> string()
202 Equivalent to read(File, []).
204 read(File::filename(), Options::proplist()) -> string()
206 Reads and processes a source file and returns the resulting
208 EDoc-text as a string. See get_doc/2 and layout/2 for options.
209 See also: file/2.
211 read_comments(File) -> [comment()]
213 Equivalent to read_comments(File, []).
215 read_comments(File::filename(), Options::proplist()) -> [comment()]
217 Extracts comments from an Erlang source code file. See the mod‐
219 ule erl_comment_scan(3) for details on the representation of
220 comments. Currently, no options are avaliable.
221 read_source(Name::File) -> [syntaxTree()]
223 Equivalent to read_source(File, []).
225 read_source(File::filename(), Options::proplist()) -> [syntaxTree()]
227 Reads an Erlang source file and returns the list of "source code
229 form" syntax trees.
230 Options:
232 {preprocess, boolean()}:
234 If the value is true, the source file will be read via the
235 Erlang preprocessor (epp). The default value is false.
236 no_preprocess is an alias for {preprocess, false}.
237 Normally, preprocessing is not necessary for EDoc to work,
239 but if a file contains too exotic definitions or uses of
240 macros, it will not be possible to read it without prepro‐
241 cessing. Note: comments in included files will not be avail‐
242 able to EDoc, even with this option enabled.
243 {includes, Path::[string()]}:
245 Specifies a list of directory names to be searched for
246 include files, if the preprocess option is turned on. Also
247 used with the @headerfile tag. The default value is the
248 empty list. The directory of the source file is always auto‐
249 matically appended to the search path.
250 {macros, [{atom(), term()}]}:
252 Specifies a list of pre-defined Erlang preprocessor (epp)
253 macro definitions, used if the preprocess option is turned
254 on. The default value is the empty list.
255 {report_missing_types, boolean()}:
257 If the value is true, warnings are issued for missing types.
258 The default value is false. no_report_missing_types is an
259 alias for {report_missing_types, false}.
260 See also: erl_syntax(3), get_doc/2.
262 run(Files::[filename()], Options::proplist()) -> ok
264 Runs EDoc on a given set of source files. Note that the doclet
266 plugin module has its own particular options; see the doclet
267 option below.
268 Also see layout/2 for layout-related options, and get_doc/2 for
270 options related to reading source files.
271 Options:
273 {app_default, string()}:
275 Specifies the default base URI for unknown applications.
276 {application, App::atom()}:
278 Specifies that the generated documentation describes the
279 application App. This mainly affects generated references.
280 {dir, filename()}:
282 Specifies the target directory for the generated documenta‐
283 tion.
284 {doc_path, [string()]}:
286 Specifies a list of URI:s pointing to directories that con‐
287 tain EDoc-generated documentation. URI without a scheme://
288 part are taken as relative to file://. (Note that such paths
289 must use / as separator, regardless of the host operating
290 system.)
291 {doclet, Module::atom()}:
293 Specifies a callback module to be used for creating the doc‐
294 umentation. The module must export a function run(Cmd,
295 Ctxt). The default doclet module is edoc_doclet; see
296 edoc_doclet:run/2 for doclet-specific options.
297 {file_suffix, string()}:
299 Specifies the suffix used for output files. The default
300 value is ".html". Note that this also affects generated ref‐
301 erences.
302 {new, boolean()}:
304 If the value is true, any existing edoc-info file in the
305 target directory will be ignored and overwritten. The
306 default value is false.
307 {source_path, [filename()]}:
309 Specifies a list of file system paths used to locate the
310 source code for packages.
311 {source_suffix, string()}:
313 Specifies the expected suffix of input files. The default
314 value is ".erl".
315 {subpackages, boolean()}:
317 If the value is true, all subpackages of specified packages
318 will also be included in the documentation. The default
319 value is false. no_subpackages is an alias for {subpackages,
320 false}.
321 Subpackage source files are found by recursively searching
323 for source code files in subdirectories of the known source
324 code root directories. (Also see the source_path option.)
325 Directory names must begin with a lowercase letter and con‐
326 tain only alphanumeric characters and underscore, or they
327 will be ignored. (For example, a subdirectory named test-
328 files will not be searched.)
329 See also: application/2, files/2.
331
333 Richard Carlsson <carlsson.richard@gmail.com>
334 edoc 0.10 edoc(3)