-spec application(atom()) -> ok.

等效于 application(Application, [])。

-spec application(App, Options) -> ok when App :: atom(), Options :: proplist().

在其默认应用程序目录中对应用程序运行 EDoc。有关详细信息，请参阅 application/3。

另请参阅：application/1。

-spec application(App, Dir, Options) -> ok when App :: atom(), Dir :: filename(), Options :: proplist().

对位于指定目录中的应用程序运行 EDoc。尝试自动设置好的默认值。除非用户另有指定

• 如果存在，则将使用 doc 子目录作为目标目录；否则将使用应用程序目录。
• 如果存在，则假定源代码位于 src 子目录中，否则位于应用程序目录本身中。
• subpackages 选项已开启。将处理所有找到的源文件。
• include 子目录会自动添加到包含路径中。（仅当 预处理 开启时才重要。）

有关详细信息，包括选项，请参阅 run/2。

另请参阅：application/2。

-spec file(filename()) -> ok.

等效于 file(Name, [])。

-spec file(Name, Options) -> ok when Name :: filename(), Options :: proplist().

读取源代码文件并将格式化的文档输出到相应的文件。

选项

{dir, filename()}

指定创建文件的输出目录。（默认情况下，输出写入源文件的目录。）

{source_suffix, string()}

指定输入文件的预期后缀。默认值为 ".erl"。

{file_suffix, string()}

指定创建文件的后缀。默认值为 ".html"。

有关更多选项，请参阅 get_doc/2 和 layout/2。

有关从 Makefile 或类似工具运行 EDoc 的信息，请参阅 edoc_run:file/1。

另请参阅：read/2。

-spec files(Files, Options) -> ok when Files :: [filename()], Options :: proplist().

等效于 run(Files, Options)。

在一组给定的源文件上运行 EDoc。有关详细信息，包括选项，请参阅 run/2。

-spec get_doc(filename()) -> {module(), edoc_module()}.

等效于 get_doc(File, [])。

-spec get_doc(File, Options) -> R
                 when
                     File :: filename(),
                     Options :: proplist(),
                     R :: {module(), edoc_module()} | {module(), edoc_module(), [entry()]}.

读取源代码文件并提取 EDoc 文档数据。请注意，如果没有环境参数（请参阅 get_doc/3），超文本链接可能不正确。

选项

{def, Macros}

• Macros = Macro | [Macro]
• Macro = {Name::atom(), Text::string() | MacroFun}
• MacroFun = fun((MacroArgument::string(), Line :: integer(), edoc_lib:edoc_env()) -> (Text::string()))

指定一组用户定义的 EDoc 宏。为宏调用替换的文本被指定为 string() 或 function()。使用宏参数文本、当前行号和当前环境调用该函数。该 fun 要返回一个 string()。有关详细信息，请参阅 宏展开。

{hidden, boolean()}

如果值为 true，则还将包括隐藏函数的文档。默认值为 false。

{private, boolean()}

如果值为 true，则还将包括私有函数的文档。默认值为 false。

{todo, boolean()}

如果值为 true，则使用 @todo 或 @TODO 标记编写的待办事项注释将包含在文档中。默认值为 false。

有关更多选项，请参阅 read_source/2、read_comments/2 和 edoc_lib:get_doc_env/3。

另请参阅：get_doc/3、layout/2、read/2、run/2、edoc_extract:source/5。

-spec get_doc(File, Env, Options) -> R
                 when
                     File :: filename(),
                     Env :: env(),
                     Options :: proplist(),
                     R :: {module(), edoc_module()} | {module(), edoc_module(), [entry()]}.

类似于 get_doc/2，但适用于给定的环境参数。Env 是由 edoc_lib:get_doc_env/3 创建的环境。

-spec layout(edoc_module()) -> string().

等效于 layout(Doc, [])。

-spec layout(Doc, Opts) -> term() when Doc :: edoc_module(), Opts :: proplist().

将 EDoc 模块文档数据转换为文本。默认布局创建 HTML 文档。

选项

{layout, Module::atom()}

指定用于格式化的回调模块。该模块必须导出函数 module(Doc, Options)。默认回调模块是 edoc_layout；有关特定于布局的选项，请参阅 edoc_layout:module/2。

另请参阅：file/2、layout/1、read/2、run/2。

-spec read(filename()) -> string().

等效于 read(File, [])。

-spec read(File, Opts) -> string() when File :: filename(), Opts :: proplist().

读取并处理源文件，并将生成的 EDoc 文本作为字符串返回。有关选项，请参阅 get_doc/2 和 layout/2。

另请参阅：file/2。

-spec read_comments(filename()) -> [comment()].

等效于 read_comments(File, [])。

-spec read_comments(File, Opts) -> [comment()] when File :: filename(), Opts :: proplist().

从 Erlang 源代码文件中提取注释。有关注释表示的详细信息，请参阅模块 erl_comment_scan。目前，没有可用的选项。

-spec read_source(filename()) -> [syntaxTree()].

等效于 read_source(File, [])。

-spec read_source(File, Opts) -> [syntaxTree()] when File :: filename(), Opts :: proplist().

读取 Erlang 源代码文件并返回“源代码形式”语法树的列表。

选项

{preprocess, boolean()}

如果值为 true，则将通过 Erlang 预处理器 (epp) 读取源文件。默认值为 false。no_preprocess 是 {preprocess, false} 的别名。

通常，预处理对于 EDoc 的工作不是必需的，但是如果文件包含过于特殊的定义或宏的使用，则在没有预处理的情况下将无法读取它。注意：即使启用了此选项，包含文件中的注释也对 EDoc 不可用。

{includes, Path::[string()]}

指定要搜索包含文件的目录名称列表（如果开启了 preprocess 选项）。也用于 @headerfile 标记。默认值为空列表。源文件的目录始终自动追加到搜索路径中。

{macros, [{atom(), term()}]}

指定预定义的 Erlang 预处理器 (epp) 宏定义列表（如果开启了 preprocess 选项）。默认值为空列表。

{report_missing_types, boolean()}

如果值为 true，则会为缺少的类型发出警告。默认值为 false。no_report_missing_types 是 {report_missing_types, false} 的别名。

{link_predefined_types, boolean()}

如果值为 true，则所有预定义的数据类型都将具有指向 erlang 模块的链接。此选项用于为 Erlang/OTP 文档生成文档。默认值为 false。no_link_predefined_types 是 {link_predefined_types, false} 的别名。

另请参阅：//syntax_tools/erl_syntax、get_doc/2。

-spec run(Files, Opts) -> ok when Files :: [filename()], Opts :: proplist().

在一组给定的源文件上运行 EDoc。请注意，doclet 插件模块有其自己的特定选项；请参阅下面的 doclet 选项。

另请参阅 layout/2 以获取与布局相关的选项，以及 get_doc/2 以获取与读取源文件相关的选项。

选项

{app_default, string()}

指定未知应用程序的默认基本 URI。

{application, App::atom()}

指定生成的文档描述的是应用 App。这主要影响生成的引用。

{dir, filename()}

指定生成文档的目标目录。

{doc_path, [string()]}

指定一个文件系统路径列表，指向包含 EDoc 生成的文档的目录。代码路径中所有应用的路径都会被自动添加。

{doclet, Module::atom()}

指定一个用于创建文档的回调模块。该模块必须导出一个函数 run(Cmd, Ctxt)。默认的 doclet 模块是 edoc_doclet；有关 doclet 特定选项，请参阅 edoc_doclet:run/2。

{file_suffix, string()}

指定输出文件使用的后缀。默认值是 ".html"。请注意，这也会影响生成的引用。

{new, boolean()}

如果该值为 true，则目标目录中任何现有的 edoc-info 文件都将被忽略并覆盖。默认值为 false。

{source_path, [filename()]}

指定一个文件系统路径列表，用于查找包的源代码。

{source_suffix, string()}

指定输入文件期望的后缀。默认值是 ".erl"。

{subpackages, boolean()}

如果该值为 true，则指定包的所有子包也将包含在文档中。默认值为 false。no_subpackages 是 {subpackages, false} 的别名。

子包源文件通过递归搜索已知源代码根目录的子目录中的源代码文件来查找。（另请参阅 source_path 选项。）目录名称必须以小写字母开头，并且仅包含字母数字字符和下划线，否则将被忽略。（例如，名为 test-files 的子目录将不会被搜索。）

另请参阅：application/2， files/2。