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() = {Line, Column, Indentation, Text}:
19
20
21           * Line = integer()
22
23           * Column = integer()
24
25           * Indentation = integer()
26
27           * Text = [string()]
28
29         edoc_module():
30
31
32           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
35         filename() = file:filename():
36
37
38         proplist() = [term()]:
39
40
41         syntaxTree() = erl_syntax:syntaxTree():
42
43

EXPORTS

45       application(Application::atom()) -> ok
46
47              Equivalent to application(Application, []).
48
49       application(Application::atom(), Options::proplist()) -> ok
50
51              Run EDoc on an application in  its  default  app-directory.  See
52              application/3 for details.
53
54              See also: application/1.
55
56       application(Application::atom(),  Dir::filename(), Options::proplist())
57       -> ok
58
59              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
63                * The doc subdirectory will be used as the  target  directory,
64                  if it exists; otherwise the application directory is used.
65
66                * 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
70                * The  subpackages option is turned on. All found source files
71                  will be processed.
72
73                * The include  subdirectory  is  automatically  added  to  the
74                  include  path.  (Only  important if  preprocessing is turned
75                  on.)
76
77              See run/2 for details, including options.
78
79              See also: application/2.
80
81       file(Name::filename()) -> ok
82
83              This function is deprecated: See file/2 for details.
84
85              Equivalent to file(Name, []).
86
87       file(Name::filename(), Options::proplist()) -> ok
88
89              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
94              Reads  a source code file and outputs formatted documentation to
95              a corresponding file.
96
97              Options:
98
99                {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
104                {source_suffix, string()}:
105                  Specifies the expected suffix of the input file. The default
106                  value is ".erl".
107
108                {file_suffix, string()}:
109                  Specifies the suffix for the created file. The default value
110                  is ".html".
111
112              See get_doc/2 and layout/2 for further options.
113
114              For   running   EDoc   from   a   Makefile   or   similar,   see
115              edoc_run:file/1.
116
117              See also: read/2.
118
119       files(Files::[filename()]) -> ok
120
121       files(Files::[filename()], Options::proplist()) -> ok
122
123              Runs EDoc on a given set of source files. See run/2 for details,
124              including options.
125
126       get_doc(File::filename()) -> {ModuleName, edoc_module()}
127
128              Equivalent to get_doc(File, []).
129
130       get_doc(File::filename(),    Options::proplist())    ->    {ModuleName,
131       edoc_module()}
132
133              Types:
134
135                 ModuleName = atom()
136
137              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
141              Options:
142
143                {def, Macros}:
144
145
146                  * Macros = Macro | [Macro]
147
148                  * Macro = {Name::atom(), Text::string()}
149
150                  Specifies  a set of EDoc macro definitions. See Inline macro
151                  expansion for details.
152
153                {hidden, boolean()}:
154                  If the value is true, documentation of hidden functions will
155                  also be included. The default value is false.
156
157                {private, boolean()}:
158                  If  the  value  is  true, documentation of private functions
159                  will also be included. The default value is false.
160
161                {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
166              See read_source/2,  read_comments/2  and  edoc_lib:get_doc_env/3
167              for further options.
168
169              See     also:     get_doc/3,     layout/2,     read/2,    run/2,
170              edoc_extract:source/5.
171
172       get_doc(File::filename(),    Env::edoc_lib:edoc_env(),    Options::pro‐
173       plist()) -> {ModuleName, edoc_module()}
174
175              Types:
176
177                 ModuleName = atom()
178
179              Like get_doc/2, but for a given environment parameter. Env is an
180              environment created by edoc_lib:get_doc_env/3.
181
182       layout(Doc::edoc_module()) -> string()
183
184              Equivalent to layout(Doc, []).
185
186       layout(Doc::edoc_module(), Options::proplist()) -> string()
187
188              Transforms EDoc module documentation data to text.  The  default
189              layout creates an HTML document.
190
191              Options:
192
193                {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
199              See also: file/2, layout/1, read/2, run/2.
200
201       read(File::filename()) -> string()
202
203              Equivalent to read(File, []).
204
205       read(File::filename(), Options::proplist()) -> string()
206
207              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
210              See also: file/2.
211
212       read_comments(File) -> [comment()]
213
214              Equivalent to read_comments(File, []).
215
216       read_comments(File::filename(), Options::proplist()) -> [comment()]
217
218              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
222       read_source(Name::File) -> [syntaxTree()]
223
224              Equivalent to read_source(File, []).
225
226       read_source(File::filename(), Options::proplist()) -> [syntaxTree()]
227
228              Reads an Erlang source file and returns the list of "source code
229              form" syntax trees.
230
231              Options:
232
233                {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
238                  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
244                {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
251                {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
256                {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
261              See also: erl_syntax(3), get_doc/2.
262
263       run(Files::[filename()], Options::proplist()) -> ok
264
265              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
269              Also see layout/2 for layout-related options, and get_doc/2  for
270              options related to reading source files.
271
272              Options:
273
274                {app_default, string()}:
275                  Specifies the default base URI for unknown applications.
276
277                {application, App::atom()}:
278                  Specifies  that  the  generated  documentation describes the
279                  application App. This mainly affects generated references.
280
281                {dir, filename()}:
282                  Specifies the target directory for the generated  documenta‐
283                  tion.
284
285                {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
292                {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
298                {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
303                {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
308                {source_path, [filename()]}:
309                  Specifies a list of file system paths  used  to  locate  the
310                  source code for packages.
311
312                {source_suffix, string()}:
313                  Specifies  the  expected  suffix of input files. The default
314                  value is ".erl".
315
316                {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
322                  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
330              See also: application/2, files/2.
331

AUTHORS

333       Richard Carlsson <carlsson.richard@gmail.com>
334
335
336
337                                   edoc 0.10                           edoc(3)
Impressum