jdk.javadoc.doclet (Java SE 9 & JDK 9 )

Doclet API提供了一个环境，结合语言模型API和编译器树API，客户端可以检查程序和库的源代码级结构，包括嵌入在源代码中的API注释。

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.LinkTree
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

从以下版本开始：: 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	可以使用标签的位置。

Package jdk.javadoc.doclet

术语

选项

与旧选项的交互。

例

Migration Guide