jdk.javadoc.doclet

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可用于过滤成员，具有以下值：
- 公众 - 只考虑公共因素
- 受保护 - 考虑公共和受保护的元素
- package - 考虑public，protected和package私有元素
- 私人 - 考虑所有元素
--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 。或者，旧选项可以继续用作新选项组合的缩写形式，如下所述： 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中的许多类型在此程序包中没有等效项。而是使用javax.lang.model和com.sun.source API中的类型。

下表提供了从旧类型到其替换的映射指南。在某些情况下，没有直接的等价物。

从以下版本开始：: 9
另请参见：: Doclet, DocletEnvironment

接口摘要
接口	描述
Doclet	用户doclet必须实现此接口，如 package description中所述。
Doclet.Option	Doclet使用的选项名称，别名，参数和描述的封装。
DocletEnvironment	表示doclet的单个调用的操作环境。
Reporter	此界面提供错误，警告和通知报告。
Taglet	doclet支持的自定义标记的接口，例如`standard doclet` 。

类摘要
类	描述
StandardDoclet	此doclet为指定的模块，包和类型生成HTML格式的文档。

枚举摘要
Enum	描述
Doclet.Option.Kind	一种选择。
DocletEnvironment.ModuleMode
Taglet.Location	可以使用标签的位置类型。

Package jdk.javadoc.doclet

术语

选项

与旧选项的交互。

例

Migration Guide