1edoc(3)                    Erlang Module Definition                    edoc(3)
2
3
4

NAME

6       edoc - EDoc - the Erlang program documentation generator.
7

DESCRIPTION

9       EDoc - the Erlang program documentation generator.
10
11       This module provides the main user interface to EDoc.
12
13         * EDoc User Manual
14
15         * Running EDoc
16

DATA TYPES

18         comment() = erl_comment_scan:comment():
19
20
21         edoc_module() = xmerl_scan:xmlElement():
22
23
24           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
27         entry()  =  #entry{name=function_name()  |  atom(),  args=[atom()   |
28         list()], line=integer(), export=boolean(), data=entry_data()}:
29
30
31           Module Entries (one per function, plus module header and footer).
32
33         entry_data() = term():
34
35
36         env() = #env{}:
37
38
39           Environment information needed by EDoc for generating references.
40
41         filename() = file:filename():
42
43
44         function_name() = {atom(), integer()}:
45
46
47         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
52
53           Module information.
54
55         ordset(T) = ordsets:ordset(T):
56
57
58         proplist() = proplists:proplist():
59
60
61         syntaxTree() = erl_syntax:syntaxTree():
62
63
64         tag() =  #tag{name=atom(),  line=integer(),  origin=comment  |  code,
65         data=term(), form=undefined | erl_parse:abstract_form()}:
66
67
68           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

EXPORTS

73       application(App::atom()) -> ok
74
75              Equivalent to application(Application, []).
76
77       application(App, Options) -> ok
78
79              Types:
80
81                 App = atom()
82                 Options = proplist()
83
84              Run EDoc on an application in its default app-directory. See ap‐
85              plication/3 for details.
86
87              See also: application/1.
88
89       application(App, Dir, Options) -> ok
90
91              Types:
92
93                 App = atom()
94                 Dir = filename()
95                 Options = proplist()
96
97              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
101                * The doc subdirectory will be used as the  target  directory,
102                  if it exists; otherwise the application directory is used.
103
104                * 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
108                * The  subpackages option is turned on. All found source files
109                  will be processed.
110
111                * The include subdirectory is automatically added to  the  in‐
112                  clude path. (Only important if  preprocessing is turned on.)
113
114              See run/2 for details, including options.
115
116              See also: application/2.
117
118       file(Name::filename()) -> ok
119
120              This function is deprecated: See file/2 for details.
121
122              Equivalent to file(Name, []).
123
124       file(Name, Options) -> ok
125
126              Types:
127
128                 Name = filename()
129                 Options = proplist()
130
131              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
136              Reads a source code file and outputs formatted documentation  to
137              a corresponding file.
138
139              Options:
140
141                {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
146                {source_suffix, string()}:
147                  Specifies the expected suffix of the input file. The default
148                  value is ".erl".
149
150                {file_suffix, string()}:
151                  Specifies the suffix for the created file. The default value
152                  is ".html".
153
154              See get_doc/2 and layout/2 for further options.
155
156              For   running   EDoc   from   a   Makefile   or   similar,   see
157              edoc_run:file/1.
158
159              See also: read/2.
160
161       files(Files::[filename()]) -> ok
162
163       files(Files, Options) -> ok
164
165              Types:
166
167                 Files = [filename()]
168                 Options = proplist()
169
170              Runs EDoc on a given set of source files. See run/2 for details,
171              including options.
172
173       get_doc(File::filename()) -> {module(), edoc_module()}
174
175              Equivalent to get_doc(File, []).
176
177       get_doc(File, Options) -> R
178
179              Types:
180
181                 File = filename()
182                 Options = proplist()
183                 R  =  {module(),  edoc_module()}  | {module(), edoc_module(),
184                 [entry()]}
185
186              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
190              Options:
191
192                {def, Macros}:
193
194
195                  * Macros = Macro | [Macro]
196
197                  * Macro = {Name::atom(), Text::string() | MacroFun}
198
199                  * MacroFun = fun((MacroArgument::string(),  Line::integer(),
200                    edoc_lib:edoc_env()) -> (Text::string()))
201
202                  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
209                {hidden, boolean()}:
210                  If the value is true, documentation of hidden functions will
211                  also be included. The default value is false.
212
213                {private, boolean()}:
214                  If  the  value  is  true, documentation of private functions
215                  will also be included. The default value is false.
216
217                {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
222              See read_source/2,  read_comments/2  and  edoc_lib:get_doc_env/3
223              for further options.
224
225              See   also:   get_doc/3,   layout/2,   read/2,  run/2,  edoc_ex‐
226              tract:source/5.
227
228       get_doc(File, Env, Options) -> R
229
230              Types:
231
232                 File = filename()
233                 Env = env()
234                 Options = proplist()
235                 R = {module(),  edoc_module()}  |  {module(),  edoc_module(),
236                 [entry()]}
237
238              Like get_doc/2, but for a given environment parameter. Env is an
239              environment created by edoc_lib:get_doc_env/3.
240
241       layout(Doc::edoc_module()) -> string()
242
243              Equivalent to layout(Doc, []).
244
245       layout(Doc, Opts) -> string()
246
247              Types:
248
249                 Doc = edoc_module()
250                 Opts = proplist()
251
252              Transforms EDoc module documentation data to text.  The  default
253              layout creates an HTML document.
254
255              Options:
256
257                {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
263              See also: file/2, layout/1, read/2, run/2.
264
265       read(File::filename()) -> string()
266
267              Equivalent to read(File, []).
268
269       read(File, Opts) -> string()
270
271              Types:
272
273                 File = filename()
274                 Opts = proplist()
275
276              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
279              See also: file/2.
280
281       read_comments(File::filename()) -> [comment()]
282
283              Equivalent to read_comments(File, []).
284
285       read_comments(File, Opts) -> [comment()]
286
287              Types:
288
289                 File = filename()
290                 Opts = proplist()
291
292              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
296       read_source(Name::filename()) -> [syntaxTree()]
297
298              Equivalent to read_source(File, []).
299
300       read_source(File, Opts) -> [syntaxTree()]
301
302              Types:
303
304                 File = filename()
305                 Opts = proplist()
306
307              Reads an Erlang source file and returns the list of "source code
308              form" syntax trees.
309
310              Options:
311
312                {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
317                  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
323                {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
330                {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
335                {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
340                {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
347              See also: erl_syntax(3), get_doc/2.
348
349       run(Files, Opts) -> ok
350
351              Types:
352
353                 Files = [filename()]
354                 Opts = proplist()
355
356              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
360              Also see layout/2 for layout-related options, and get_doc/2  for
361              options related to reading source files.
362
363              Options:
364
365                {app_default, string()}:
366                  Specifies the default base URI for unknown applications.
367
368                {application, App::atom()}:
369                  Specifies that the generated documentation describes the ap‐
370                  plication App. This mainly affects generated references.
371
372                {dir, filename()}:
373                  Specifies the target directory for the generated  documenta‐
374                  tion.
375
376                {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
381                {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
387                {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
392                {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
397                {source_path, [filename()]}:
398                  Specifies a list of file system paths  used  to  locate  the
399                  source code for packages.
400
401                {source_suffix, string()}:
402                  Specifies  the  expected  suffix of input files. The default
403                  value is ".erl".
404
405                {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
411                  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
419              See also: application/2, files/2.
420

AUTHORS

422       Richard Carlsson <carlsson.richard@gmail.com>
423
424
425
426                                   edoc 1.2                            edoc(3)
Impressum