java中let_Java Doclet

Java Doclet

[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

org.apache.maven.plugins

maven-javadoc-plugin

3.1.1

UTF-8

false

com.my.CustomMavenDoclet

com.my.component

doclet

1.0-SNAPSHOT

9. Java9之后的javadoc

java9的javadoc做了较大改变，代码放到了模块jdk.javadoc下，比如外部入口类是jdk.javadoc.internal.tool.Main。

10. javadoc选项及参数说明

-开头是选项的名字

@是从指定文件加载选项即参数

- sourcepath：指定源码地址，多个路径以:分割

javadoc的参数可以是类名，也可以是包名，但是如果是包，javadoc只生成指定包下的类，不支持递归。