Module
jdk.javadoc
Package jdk.javadoc.doclet
Doclet API提供了一个环境,结合语言模型API和编译器树API,客户端可以检查程序和库的源代码级结构,包括嵌入在源代码中的API注释。
com.sun.source.doctree.SeeTree SerialFieldTag com.sun.source.doctree.SerialFieldTree SourcePosition com.sun.source.util.SourcePositions Tag com.sun.source.doctree.DocTree ThrowsTag com.sun.source.doctree.ThrowsTree Type javax.lang.model.type.Type TypeVariable javax.lang.model.type.TypeVariable WildcardType javax.lang.model.type.WildcardType
standard doclet
可用于生成HTML格式的文档。 它支持用户定义的taglets
,可用于在文档注释中为用户定义的标签生成自定义输出。
注意:此包中的声明取代了较旧的包com.sun.javadoc
。 有关旧类型映射到新类型的详细信息,请参阅Migration Guide 。
Doclet由javadoc调用,该API可用于将程序信息写入文件。 例如,默认情况下调用标准doclet,以生成HTML文档。
调用由界面Doclet
- run
接口方法定义,定义入口点。
public boolean run(DocletEnvironment environment)
DocletEnvironment
实例保存了doclet将被初始化的环境。
从这个环境可以提取所有其他信息,形式为elements
。
可以进一步使用Language Model API
描述的API和实用程序查询元素和类型。
术语
- 已选
- 一个元件被认为是要被选择 ,如果选择控制 allow它被记录。 (请注意,从不选择合成元素。)
- 指定
- 用户指定的元素集合被认为是指定元素 。 指定元素用于确定要记录的包括元件提供的出发点。
- 包括
- 一个元素被认为是包含的 ,如果它被指定,如果它包含一个指定的元素,或者它被包含在一个指定的元素中,并被选中 。 包含的元素将被记录。
选项
可以使用以下选项来指定Javadoc 选择控件 :-
--show-members:value
和--show-types:value
可用于过滤成员,具有以下值:- 公众 - 只考虑公共元素
- 保护 - 考虑公共和受保护的元素
- 包 - 考虑公共,保护和包私有元素
- 私人 - 考虑所有元素
-
--show-packages:value
“导出”或“全部”可用于仅考虑导出的包或模块中的所有包。 - 可以使用
--show-module-contents:value
指定级别的模块声明可以记录。 值“api”表示API级别的文档,“all”表示详细的文档。
-
--module
文件指定的模块。 -
--expand-requires:value
通过包括一些或所有模块依赖关系扩展要记录的模块集。 该值可能是以下之一:- 传递 - 在命令行上明确指定的每个模块被扩展为包括其传递依赖关系
- 所有 - 在命令行上明确指定的每个模块都被扩展为包括其传递依赖关系的关闭,以及它的所有直接依赖
-
packagenames
可以用来指定包。 -
-subpackages
可以用于递归加载包。 - 可以使用
-exclude
排除包目录。 -
sourcefilenames
可以用来指定源文件名。
与旧选项的交互。
新的--show-*
选项提供了更旧的选项-public,-protected,-package,-private的更详细的替代。
或者,较旧的选项可以继续用作新选项组合的较短表单,如下所述:
Short form options mapping Older option Equivalent to these values with the new option --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,它显示一个类及其成员的信息,支持一个选项。 // note imports deleted for clarity
public class Example implements Doclet {
Reporter reporter;
@Override
public void init(Locale locale, Reporter reporter) {
reporter.print(Kind.NOTE, "Doclet using locale: " + locale);
this.reporter = reporter;
}
public void printElement(DocTrees trees, Element e) {
DocCommentTree docCommentTree = trees.getDocCommentTree(e);
if (docCommentTree != null) {
System.out.println("Element (" + e.getKind() + ": "
+ e + ") has the following comments:");
System.out.println("Entire body: " + docCommentTree.getFullBody());
System.out.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) {
System.out.println("Overview html: " + docCommentTree.getFullBody());
}
} catch (IOException missing) {
reporter.print(Kind.ERROR, "No overview.html found.");
}
for (TypeElement t : ElementFilter.typesIn(docEnv.getIncludedElements())) {
System.out.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 = Arrays.asList(
"-overviewfile",
"--overview-file",
"-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 new HashSet<>(Arrays.asList(options));
}
@Override
public SourceVersion getSupportedSourceVersion() {
// support the latest release
return SourceVersion.latest();
}
}
可以使用命令行调用此doclet,例如:
javadoc -doclet Example \
-overviewfile overview.html \
-sourcepath source-location \
source-location/Example.java
Migration Guide
旧的com.sun.javadoc
API中的许多类型在此程序包中没有等同内容。 而是使用javax.lang.model
和com.sun.source
API中的类型。
下表给出了从旧类型到替换的映射的指南。 在某些情况下,没有直接的等价物。
Guide for mapping old types to new types Old Type New Type AnnotatedType javax.lang.model.type.Type AnnotationDesc javax.lang.model.element.AnnotationMirror AnnotationDesc.ElementValuePair javax.lang.model.element.AnnotationValue AnnotationTypeDoc javax.lang.model.element.TypeElement AnnotationTypeElementDoc javax.lang.model.element.ExecutableElement AnnotationValue javax.lang.model.element.AnnotationValue ClassDoc javax.lang.model.element.TypeElement ConstructorDoc javax.lang.model.element.ExecutableElement Doc javax.lang.model.element.Element DocErrorReporter jdk.javadoc.doclet.Reporter Doclet jdk.javadoc.doclet.Doclet ExecutableMemberDoc javax.lang.model.element.ExecutableElement FieldDoc javax.lang.model.element.VariableElement LanguageVersion javax.lang.model.SourceVersion MemberDoc javax.lang.model.element.Element MethodDoc javax.lang.model.element.ExecutableElement PackageDoc javax.lang.model.element.PackageElement Parameter javax.lang.model.element.VariableElement ParameterizedType javax.lang.model.type.DeclaredType ParamTag com.sun.source.doctree.ParamTree ProgramElementDoc javax.lang.model.element.Element RootDoc jdk.javadoc.doclet.DocletEnvironment SeeTag com.sun.source.doctree.LinkTreecom.sun.source.doctree.SeeTree SerialFieldTag com.sun.source.doctree.SerialFieldTree SourcePosition com.sun.source.util.SourcePositions Tag com.sun.source.doctree.DocTree ThrowsTag com.sun.source.doctree.ThrowsTree Type javax.lang.model.type.Type TypeVariable javax.lang.model.type.TypeVariable WildcardType javax.lang.model.type.WildcardType
- 从以下版本开始:
- 9
- 另请参见:
-
Doclet
,DocletEnvironment
-
接口摘要 接口 描述 Doclet 用户doclet必须实现此接口,如 package description中所述。Doclet.Option Doclet使用的选项名称,别名,参数和描述的封装。DocletEnvironment 表示单次调用doclet的操作环境。Reporter 此界面提供错误,警告和通知报告。Taglet 由doclet支持的自定义标签的界面,如standard doclet
。 -
类摘要 Class 描述 StandardDoclet 该doclet为指定的模块,包和类型生成HTML格式的文档。 -
枚举摘要 Enum 描述 Doclet.Option.Kind 这种选择。DocletEnvironment.ModuleMode Taglet.Location 可以使用标签的位置。