19
%% @copyright 2001-2003 Richard Carlsson
20
%% @author Richard Carlsson <richardc@csd.uu.se>
21
%% [http://www.csd.uu.se/~richardc/]
19
%% @copyright 2001-2007 Richard Carlsson
20
%% @author Richard Carlsson <richardc@it.uu.se>
21
%% @version {@version}
24
23
%% =====================================================================
26
%% @TODO check weirdness in name generation for @spec f(TypeName, ...) -> ...
27
%% @TODO option for ignoring functions matching some pattern ('..._test_'/0)
28
%% @TODO @private_type tag, opaque unless generating private docs?
29
%% @TODO document the record type syntax
30
%% @TODO document the @docfile and @headerfile tags, with includes-option
31
%% @TODO some 'skip' option for ignoring particular modules/packages?
32
%% @TODO intermediate-level packages: document even if no local sources.
33
%% @TODO multiline comment support (needs modified comment representation)
34
%% @TODO config-file for default settings
35
%% @TODO config: locations of all local docdirs; generate local doc-index page
36
%% @TODO config: URL:s of offline packages/apps
37
%% @TODO config: default stylesheet
38
%% @TODO config: default header/footer, etc.
39
%% @TODO offline linkage
25
%% TODO: check weirdness in name generation for @spec f(TypeName, ...) -> ...
26
%% TODO: option for ignoring functions matching some pattern ('..._test_'/0)
27
%% TODO: @private_type tag, opaque unless generating private docs?
28
%% TODO: document the record type syntax
29
%% TODO: some 'skip' option for ignoring particular modules/packages?
30
%% TODO: intermediate-level packages: document even if no local sources.
31
%% TODO: multiline comment support (needs modified comment representation)
32
%% TODO: config-file for default settings
33
%% TODO: config: locations of all local docdirs; generate local doc-index page
34
%% TODO: config: URL:s of offline packages/apps
35
%% TODO: config: default stylesheet
36
%% TODO: config: default header/footer, etc.
37
%% TODO: offline linkage
38
%% TODO: including source code, explicitly and/or automatically
41
40
%% @doc EDoc - the Erlang program documentation generator.
43
42
%% This module provides the main user interface to EDoc.
45
44
%% <li><a href="overview-summary.html">EDoc User Manual</a></li>
46
%% <li><a href="overview-summary.html#usage">Running EDoc</a></li>
45
%% <li><a href="overview-summary.html#Running_EDoc">Running EDoc</a></li>
74
%% @spec file(filename(), option_list()) -> ok
73
%% @spec file(filename(), proplist()) -> ok
76
75
%% @type filename() = //kernel/file:filename()
77
%% @type option_list() = [term()]
76
%% @type proplist() = [term()]
79
78
%% @deprecated This is part of the old interface to EDoc and is mainly
80
79
%% kept for backwards compatibility. The preferred way of generating
126
125
edoc_lib:write_file(Text, Dir, BaseName ++ Suffix).
129
%% @TODO better documentation of files/1/2, packages/1/2, application/1/2/3
128
%% TODO: better documentation of files/1/2, packages/1/2, application/1/2/3
131
130
%% @spec (Files::[filename() | {package(), [filename()]}]) -> ok
132
131
%% @equiv packages(Packages, [])
135
134
files(Files, []).
137
136
%% @spec (Files::[filename() | {package(), [filename()]}],
138
%% Options::option_list()) -> ok
137
%% Options::proplist()) -> ok
139
138
%% @doc Runs EDoc on a given set of source files. See {@link run/3} for
139
%% details, including options.
141
140
%% @equiv run([], Files, Options)
143
142
files(Files, Options) ->
149
148
packages(Packages) ->
150
149
packages(Packages, []).
152
%% @spec (Packages::[package()], Options::option_list()) -> ok
151
%% @spec (Packages::[package()], Options::proplist()) -> ok
153
152
%% @type package() = atom() | string()
155
154
%% @doc Runs EDoc on a set of packages. The `source_path' option is used
156
%% to locate the files; see {@link run/3} for details. This function
157
%% automatically appends the current directory to the source path.
155
%% to locate the files; see {@link run/3} for details, including
156
%% options. This function automatically appends the current directory to
159
159
%% @equiv run(Packages, [], Options)
185
%% @spec (Application::atom(), Dir::filename(), Options::option_list())
185
%% @spec (Application::atom(), Dir::filename(), Options::proplist())
187
187
%% @doc Run EDoc on an application located in the specified directory.
188
188
%% Tries to automatically set up good defaults. Unless the user
261
261
%% @spec run(Packages::[package()],
262
262
%% Files::[filename() | {package(), [filename()]}],
263
%% Options::option_list()) -> ok
263
%% Options::proplist()) -> ok
264
264
%% @doc Runs EDoc on a given set of source files and/or packages. Note
265
265
%% that the doclet plugin module has its own particular options; see the
266
266
%% `doclet' option below.
268
%% Also see {@link edoc:layout/2} for layout-related options, and
269
%% {@link edoc:get_doc/2} for options related to reading source
268
%% Also see {@link layout/2} for layout-related options, and
269
%% {@link get_doc/2} for options related to reading source
580
581
read_comments(File) ->
581
582
read_comments(File, []).
583
%% @spec read_comments(File::filename(), Options::option_list()) ->
584
%% @spec read_comments(File::filename(), Options::proplist()) ->
586
%% comment() = {Line, Column, Indentation, Text}
588
%% Column = integer()
589
%% Indentation = integer()
587
%% comment() = {Line, Column, Indentation, Text},
589
%% Column = integer(),
590
%% Indentation = integer(),
590
591
%% Text = [string()]
592
593
%% @doc Extracts comments from an Erlang source code file. See the
628
629
%% <dt>{@type {includes, Path::[string()]@}}
630
631
%% <dd>Specifies a list of directory names to be searched for include
631
%% files, if the `preprocess' option is turned on. The default
632
%% value is the empty list. The directory of the source file is
633
%% always automatically appended to the search path.
632
%% files, if the `preprocess' option is turned on. Also used with
633
%% the `@headerfile' tag. The default value is the empty list. The
634
%% directory of the source file is always automatically appended to
635
637
%% <dt>{@type {macros, [{atom(), term()@}]@}}
717
719
%% <li>`Macro' = {@type {Name::atom(), Text::string()@}}</li>
719
721
%% Specifies a set of EDoc macro definitions. See
720
%% <a href="overview-summary.html#macros">Inline macro expansion</a>
722
%% <a href="overview-summary.html#Macro_expansion">Inline macro expansion</a>
723
725
%% <dt>{@type {hidden, bool()@}}
754
757
get_doc(File, Env, Opts).
756
759
%% @spec get_doc(File::filename(), Env::edoc_lib:edoc_env(),
757
%% Options::option_list()) -> {ModuleName, edoc_module()}
760
%% Options::proplist()) -> {ModuleName, edoc_module()}
758
761
%% ModuleName = atom()
760
763
%% @doc Like {@link get_doc/2}, but for a given environment
added
removed
lib/edoc/src/edoc.erl
