[TOC]

1. 简介

Doclet是用Java编程语言编写的程序，它用doclet API指定Javadoc工具的输出内容和格式。缺省情况下，Javadoc工具用Sun提供的"标准"doclet来生成HTML形式的API文档。然而，用户也可用自己的doclet根据个人喜好自定义Javadoc输出。用户可以利用doclet API从头开始编写doclet，也可以对标准doclet进行修改，以适合自己的需要。

2. 创建自己的Doclet

引入doclet API
引入 import com.sun.javadoc.* ，程序的入口方法是 public static boolean start(RootDoc root)

import com.sun.javadoc.*;
public class ListClass {
    public static boolean start(RootDoc root) {
        ClassDoc[] classes = root.classes();
        for (int i = 0; i < classes.length; ++i) {
            System.out.println(classes[i]);
        return true;
javac ListClass.java 
javadoc运行
javadoc -doclet ListClass -docletpath .  MyClass.java
3. 自定义标签的处理
注释中包含如下标签
@mytag Some dummy text
通过Doc或者其子类的tags(String)方法获取，返回："Some dummy text."
method.tags("mytag")
import com.sun.javadoc.*;
public class ListTags {
    public static boolean start(RootDoc root){ 
        String tagName = "mytag";
        writeContents(root.classes(), tagName);
        return true;
    private static void writeContents(ClassDoc[] classes, String tagName) {
        for (int i = 0; i < classes.length; i++) {
            boolean classNamePrinted = false;
            MethodDoc[] methods = classes[i].methods();
            for (int j = 0; j < methods.length; j++) {
                Tag[] tags = methods[j].tags(tagName);
                if (tags.length > 0) {
                    if (!classNamePrinted) {
                        System.out.println("\n" + classes[i].name() + "\n");
                        classNamePrinted = true;
                    System.out.println(methods[j].name());
                    for (int k = 0; k < tags.length; k++) {
                        System.out.println("   " + tags[k].name() + ": " + tags[k].text());
4. 自定义命令行选项
新增自定义选项的名字可以自定义，但是选项默认是无参数，如果需要参数，则需要做额外工作。
选项的结构
Rootdoc.options()方法返回一个二维String数组 String[][]，如下：
options()[0][0] = "-foo"
options()[0][1] = "this"
options()[0][2] = "that"
options()[1][0] = "-bar"
options()[1][1] = "other"
自定义选项参数个数
每个选项的参数个数是不定，需要自定义Doclet拥有一个public static int optionLength(String option)方法：
   public static int optionLength(String option) {
        if(option.equals("-tag")) {
            return 2;
        return 0;
返回值是参数的个数，如果是不需识别的选项，返回0即可。
自定义选项参数校验
参数校验需要自定义Doclet拥有一个public static boolean validOptions(String options[][], DocErrorReporter reporter)方法：
public static boolean validOptions(String options[][], 
                                       DocErrorReporter reporter) {
        boolean foundTagOption = false;
        for (int i = 0; i < options.length; i++) {
            String[] opt = options[i];
            if (opt[0].equals("-tag")) {
                if (foundTagOption) {
                    reporter.printError("Only one -tag option allowed.");
                    return false;
                } else { 
                    foundTagOption = true;
        if (!foundTagOption) {
            reporter.printError("Usage: javadoc -tag mytag -doclet ListTags ...");
        return foundTagOption;
方法内实现参数校验逻辑，并通过DocErrorReporter.printError打印错误信息。
抽象的Doclet类
JDK中提供了一个抽象的Doclet类，可直接继承使用。因为RootDoc的实现类RootDocImpl并没面向接口实现，而是利用反射实现了鸭子类型，可参考类com.sun.tools.javadoc.main.DocletInvoker的实现。所以继承com.sun.javadoc.Doclet抽象类并不是必须的。
package com.sun.javadoc;
@Deprecated(since="9", forRemoval=true)
@SuppressWarnings("removal")
public abstract class Doclet {
    public static boolean start(RootDoc root) {
        return true;
    public static int optionLength(String option) {
        return 0;  // default is option unknown
    public static boolean validOptions(String options[][],
                                       DocErrorReporter reporter) {
        return true;  // default is options are valid
    public static LanguageVersion languageVersion() {
        return LanguageVersion.JAVA_1_1;
5. javadoc工具的外部入口
外部入口类com.sun.tools.javadoc.Main：
package com.sun.tools.javadoc;
public class Main {
    private Main() {
     * Command line interface.
     * @param args   The command line parameters.
    public static void main(String... args) {
        System.exit(execute(args));
     * Programmatic interface.
     * @param args   The command line parameters.
     * @return The return code.
    public static int execute(String... args) {
        Start jdoc = new Start();
        return jdoc.begin(args);
    ......
如果需要在代码中出发执行javadoc，可以这么做：
import com.sun.tools.javadoc.Main;
String[] commandLineParams = new String[]{
    "-encoding", "utf-8",
    "-sourcepath", "/path/to/src/main/java"
Main.execute(commandLineParams);
commandLineParams为命令行的参数数组。
6. 获取泛型类型
泛型是JDK5之后才有的，所以要指定语言版本：
public static LanguageVersion languageVersion() {
    return LanguageVersion.JAVA_1_5;
获取方式：
if (type instanceof ParameterizedType) {
    ParameterizedType pt = type.asParameterizedType();
    Type[] typeArgs = pt.typeArguments();
7. 获取私有类、私有属性、私有方法
获取私有属性和私有方法可以通过传入参数实现
public static boolean start(RootDoc root) {
    ClassDoc[] classes = root.classes();
    for (ClassDoc cls : classes) {
        System.out.println(cls);
        FieldDoc[] fields = cls.fields(false); // 获取包含私有属性在内的所有属性
        for (FieldDoc flc : fields) {
            System.out.println(flc);
        MethodDoc[] methods = cls.methods(false);  // 获取包含私有方法在内的所有方法
        for (MethodDoc meth : methods) {
            System.out.println(meth);
    return true;
获取私有类只能通过传入-private选项给javadoc实现。
8. Maven中使用自定义Doclet
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.1.1</version>
    <configuration>
        <encoding>UTF-8</encoding>
        <useStandardDocletOptions>false</useStandardDocletOptions>
        <doclet>com.my.CustomMavenDoclet</doclet>
        <docletArtifacts>
            <docletArtifact>
                <groupId>com.my.component</groupId>
                <artifactId>doclet</artifactId>
                <version>1.0-SNAPSHOT</version>
            </docletArtifact>
        </docletArtifacts>
    </configuration>
</plugin>
9. Java9之后的javadoc
java9的javadoc做了较大改变，代码放到了模块jdk.javadoc下，比如外部入口类是jdk.javadoc.internal.tool.Main。