Module jdk.javadoc
Package jdk.javadoc.doclet
package jdk.javadoc.doclet
Doclet API提供了一个环境，与语言模型API和编译器树API一起，允许客户端检查程序和库的源级结构，包括源代码中嵌入的API注释。
可以使用标准doclet来生成HTML格式的文档。它支持用户定义的taglets，可用于为文档注释中的用户定义标签生成定制输出。
注意：此包中的声明取代了旧包com.sun.javadoc中的声明。有关旧类型到新类型的映射详细信息，请参阅迁移指南。
Doclet由javadoc调用，此API可用于将程序信息写入文件。例如，默认情况下会调用标准doclet来生成HTML文档。
调用由接口Doclet定义 -- run接口方法定义了入口点。
public boolean run(DocletEnvironment environment)
DocletEnvironment实例保存了doclet将被初始化的环境。从这个环境中可以提取所有其他信息，以elements的形式。可以进一步使用语言模型API描述的API和实用程序来查询元素和类型。
术语
- 已选择
- 如果选择控件允许文档化，则认为元素已被选择。（请注意，合成元素永远不会被选择。）
- 已指定
- 用户指定的元素集被视为指定元素。指定元素为确定要文档化的包含元素提供了起点。
- 已包含
-
如果元素已被选择，并且以下任一条件为真，则认为元素已被包含：
- 元素已被指定，或
- 元素包含一个指定元素，或
- 元素被包含在一个指定元素中。
选项
Javadoc 选择控件可以通过以下选项指定如下：--show-members:value和--show-types:value可用于过滤成员，具体取决于以下值：- public -- 仅考虑公共元素
- protected -- 考虑公共和受保护的元素
- package -- 考虑公共、受保护和包私有元素
- private -- 考虑所有元素
--show-packages:value可以使用"exported"或"all"来仅考虑导出的包或模块中的所有包。--show-module-contents:value可用于指定模块声明的文档级别。值"api"表示API级别文档，"all"表示详细文档。
--module文档化指定的模块。--expand-requires:value通过包含一些或所有模块依赖项来扩展要文档化的模块集。值可以是：- transitive -- 明确在命令行上指定的每个模块都会扩展为包含其传递依赖项的闭包
- all -- 明确在命令行上指定的每个模块都会扩展为包含其传递依赖项的闭包，以及所有直接依赖项
packagenames可用于指定包。-subpackages可用于递归加载包。-exclude可用于排除包目录。sourcefilenames可用于指定源文件名。
与旧选项的交互
新的--show-*选项提供了对旧选项-public、-protected、-package、-private更详细的替代方案。或者，旧选项可以继续用作新选项的组合的缩写形式，如下所述：
| 旧选项 | 等效于这些值与新选项 | ||||
|---|---|---|---|---|---|
--show-members |
--show-types |
--show-packages |
--show-module-contents |
||
-public |
public | public | exported | api | |
-protected |
protected | protected | exported | api | |
-package |
package | package | all | all | |
-private |
private | private | all | all | |
限定元素名称是指其包名前置的名称，例如java.lang.String。非限定名称没有包名，例如String。
示例
以下是一个显示类及其成员信息的示例doclet，支持一个选项。// 注意：为清晰起见已删除导入
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
- 参见: