模块 jdk.javadoc
包 jdk.javadoc.doclet
包jdk.javadoc.doclet
Doclet API 提供了一个环境，结合语言模型 API 和编译器树 API，允许客户端检查程序和库的源代码级结构，包括嵌入在源代码中的 API 注解。
standard doclet 可用于生成 HTML 格式的文档。它支持用户定义的 taglets ，可用于为文档注释中的用户定义标签生成自定义输出。
笔记：此包中的声明取代旧包 com.sun.javadoc 中的声明。有关旧类型到新类型映射的详细信息，请参阅 迁移指南。
Doclet 由 javadoc 调用，此 API 可用于将程序信息写入文件。例如，默认调用标准 doclet 以生成 HTML 文档。
调用由接口Doclet 定义——run 接口方法，定义入口点。
public boolean run(DocletEnvironment environment)
DocletEnvironment 实例保存 doclet 将被初始化的环境。可以从这个环境中提取所有其他信息，形式为 elements 。可以进一步使用 Language Model API 描述的 API 和实用程序来查询元素和类型。
术语
- 已选
- 一个元素被认为是 selected ，如果 selection controls 允许 它被记录。 （请注意，永远不会选择合成元素。）
- 指定
- 用户指定的元素集被认为是 specified elements 。指定的元素提供了确定要记录的 included elements 的起点。
- 包括在内
- 一个元素被认为是 included ，如果它是 specified 如果它包含一个 specified 元素，或者它被包含在一个 specified 元素中，并且是 selected 。包含的元素将被记录。
选项
可以使用这些选项指定 Javadoc selection control，如下所示：--show-members:value和--show-types:value可以用来过滤成员，取值如下：- public——只考虑公共元素
- 受保护——考虑公共和受保护的元素
- 包——考虑公共、受保护和包私有元素
- 私有——考虑所有元素
--show-packages:value“exported”或“all”可用于仅考虑导出的包或模块中的所有包。--show-module-contents:value可用于指定可以记录模块声明的级别。 “api”的值表示 API 级别的文档，“all”表示详细的文档。
--module记录指定的模块。--expand-requires:value通过包含部分或全部模块依赖项来扩展要记录的模块集。该值可能是以下之一：- 传递性——在命令行上明确指定的每个模块都被扩展以包括其传递依赖项的关闭
- all -- 在命令行上明确指定的每个模块都被扩展以包括其传递依赖项的闭包，以及它的所有直接依赖项
packagenames可用于指定包。-subpackages可用于递归加载包。-exclude可用于排除包目录。sourcefilenames可用于指定源文件名。
与旧选项的交互。
新的--show-* 选项为旧选项 -public、-protected、-package、-private 提供了更详细的替换。或者，旧选项可以继续用作新选项组合的较短形式，如下所述：
| 较旧的选项 | 与新选项等同于这些值 | ||||
|---|---|---|---|---|---|
--show-members |
--show-types |
--show-packages |
--show-module-contents |
||
-public |
public | public | 输出 | 应用程序接口 | |
-protected |
protected | protected | 输出 | 应用程序接口 | |
-package |
包 | 包 | all | all | |
-private |
私人的 | 私人的 | all | all | |
qualified 元素名称是在其前面加上包名称的元素名称，例如 java.lang.String 。非限定名称没有包名称，例如 String 。
示例
以下是一个示例 doclet，它显示一个类及其成员的信息，支持一个选项。// Note: imports deleted for clarity
public class Example implements Doclet {
private Reporter reporter;
private PrintWriter stdout;
@Override
public void init(Locale locale, Reporter reporter) {
reporter.print(Kind.NOTE, "Doclet using locale: " + locale);
this.reporter = reporter;
stdout = reporter.getStandardWriter();
}
public void printElement(DocTrees trees, Element e) {
DocCommentTree docCommentTree = trees.getDocCommentTree(e);
if (docCommentTree != null) {
stdout.println("Element (" + e.getKind() + ": "
+ e + ") has the following comments:");
stdout.println("Entire body: " + docCommentTree.getFullBody());
stdout.println("Block tags: " + docCommentTree.getBlockTags());
}
}
@Override
public boolean run(DocletEnvironment docEnv) {
reporter.print(Kind.NOTE, "overviewFile: " + overviewFile);
// get the DocTrees utility class to access document comments
DocTrees docTrees = docEnv.getDocTrees();
// location of an element in the same directory as overview.html
try {
Element e = ElementFilter.typesIn(docEnv.getSpecifiedElements()).iterator().next();
DocCommentTree docCommentTree
= docTrees.getDocCommentTree(e, overviewFile);
if (docCommentTree != null) {
stdout.println("Overview html: " + docCommentTree.getFullBody());
}
} catch (IOException missing) {
reporter.print(Kind.ERROR, "No overview.html found.");
}
for (TypeElement t : ElementFilter.typesIn(docEnv.getIncludedElements())) {
stdout.println(t.getKind() + ":" + t);
for (Element e : t.getEnclosedElements()) {
printElement(docTrees, e);
}
}
return true;
}
@Override
public String getName() {
return "Example";
}
private String overviewFile;
@Override
public Set<? extends Option> getSupportedOptions() {
Option[] options = {
new Option() {
private final List<String> someOption = List.of(
"--overview-file",
"-overviewfile",
"-o"
);
@Override
public int getArgumentCount() {
return 1;
}
@Override
public String getDescription() {
return "an option with aliases";
}
@Override
public Option.Kind getKind() {
return Option.Kind.STANDARD;
}
@Override
public List<String> getNames() {
return someOption;
}
@Override
public String getParameters() {
return "file";
}
@Override
public boolean process(String opt, List<String> arguments) {
overviewFile = arguments.get(0);
return true;
}
}
};
return Set.of(options);
}
@Override
public SourceVersion getSupportedSourceVersion() {
// support the latest release
return SourceVersion.latest();
}
}
可以使用命令行调用此 doclet，例如：
javadoc -docletpath doclet-classes \
-doclet Example \
--overview-file overview.html \
--source-path source-location \
source-location/Example.java
迁移指南
旧 com.sun.javadoc API 中的许多类型在此包中没有等效项。相反，使用 javax.lang.model 和 com.sun.source API 中的类型。
下表提供了从旧类型到替代类型的映射指南。在某些情况下，没有直接的等价物。
- 自从：
- 9
- 参见：
-
类描述用户 doclet 必须实现此接口，如 包装说明 中所述。Doclet 使用的选项名称、别名、参数和描述的封装。一种选择。表示单次调用 doclet 的操作环境。指定模块文档详细程度的模式。用于报告诊断和其他消息的接口。此 doclet 为指定的模块、包和类型生成 HTML 格式的文档。doclet 支持的自定义 taglet 的接口，例如
standard doclet。可以使用标签的位置类型。