javadoc:jdk 9通过javadoc API读取java源码中的注释信息(comment)

几年前写过一博客：《java:通过javadoc API读取java源码中的注释信息(comment)》，简单介绍了通过javadoc API读取源码注释的流程。
那时还是用JDK 1.8。但是在JDK9环境下JDK 1.8的那一套API就不能用了。JDK 9提供了一套新的javadoc API实现注释代码的读取，即jdk.javadoc 模块。
本文说明如何基于jdk.javadoc来读取源码的注释。

module-info.java

需要在你的项目module-info.java中如下添加jdk.javadoc引用。

module you_module_name{exports you.package.name;requires transitive  jdk.javadoc;
}

类型迁移

从JDK 1.8迁移到JDK 9是个挺麻烦的事儿，
下面列表出了JDK 1.8下javadoc API与JDK 9提供的类型对应表。

此表只能做为基本的参照，其实许多类型在没有完全等价的类型。

Old Type(JDK8)	New Type(JDK9)
AnnotatedType	`javax.lang.model.type.TypeMirror`
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.TypeMirror`
TypeVariable	`javax.lang.model.type.TypeVariable`
WildcardType	`javax.lang.model.type.WildcardType`

Doclet

JDK 1.8中Doclet的定义很随意，只要有一个start静态方法就可以了。如下：

	public static  class Doclet {public Doclet() {}public static boolean start(RootDoc root) {// 获取 javadoc根数据对象，从该根对象可以提取所有其他程序结构信息JavaDocReader.root = root;return true;}}

但JDK9中对doclet类型做接口化约束，要求doclet必须实现jdk.javadoc.doclet.Doclet接口，示例如下：

	public static class DocletExample implements jdk.javadoc.doclet.Doclet {private DocletEnvironment docEnv;@Overridepublic void init(Locale locale, Reporter reporter) {}@Overridepublic boolean run(DocletEnvironment docEnv) {// 表示单次调用doclet的操作环境。此对象可用于访问命令行上的程序结构、各种实用程序和用户指定的元素。// 对应与JDK 1.8下的RootDocthis.docEnv = docEnv;return true;}@Overridepublic String getName() {return "DocletExample";}@Overridepublic Set<? extends Option> getSupportedOptions() {return Set.of();}@Overridepublic SourceVersion getSupportedSourceVersion() {return SourceVersion.latest();}}

JavadocTool

JDK 1.8下程序执行javadoc直接调用com.sun.tools.javadoc.Main中的main或execute静态方法。
在JDK 9下com.sun.tools.javadoc.Main已经不存在了。JDK 9对JDK 命令行工具进行了统一封装为ToolProvider接口，需要使用ToolProvider机制获取JavadocToolProvider执行javadoc.

/** 获取 javadoc tool */
ToolProvider javadocTool = ToolProvider.findFirst("javadoc").orElseThrow();
/** 执行javadoc */
javadocTool.run(System.out,System.err,new String[] {....});

实现代码

以下是基于jdk.javadoc实现的读取源码注释的示例代码，实现读取指定的包下的所有源码注释，并输出每个类及类成员的注解。

import org.junit.Test;
import static org.junit.Assert.*;import java.util.List;
import java.util.Locale;
import java.util.Set;
import java.util.spi.ToolProvider;import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.element.TypeElement;
import javax.lang.model.util.ElementFilter;
import javax.lang.model.util.Elements;
import javax.tools.Diagnostic.Kind;import com.sun.source.doctree.BlockTagTree;
import com.sun.source.doctree.DocCommentTree;
import com.sun.source.util.DocTrees;import jdk.javadoc.doclet.Doclet;
import jdk.javadoc.doclet.DocletEnvironment;
import jdk.javadoc.doclet.Reporter;/*** JDK 9的javadoc tool 调用测试* @author guyadong**/
public class JavadocToolTest {@Testpublic void testJavadocTool() {try {/** 获取 javadoc tool */ToolProvider javadocTool = ToolProvider.findFirst("javadoc").orElseThrow();int returnCode = javadocTool.run(System.out,System.err,new String[] {/** 指定自定义的  Doclet 接口实现类(全名)  */"-doclet", DocletExample.class.getName(), /** 指定-doclet选项定义类名的所在的类搜索路径  */"-docletpath", DocletExample.class.getProtectionDomain().getCodeSource().getLocation().getPath(),/** --subpackages 要获取注释的包名 */"-subpackages",	"net.gdface.utils",/** --sourcepath 要源码路径 */"-sourcepath","D:/j/common-java/common-base/src/main/java",/** --classpath 指定javadoc执行时搜索引用类的路径 */"-classpath","D:/j/common-java/common-base/target/classes","-encoding","utf-8"});if(0 != returnCode){System.out.printf("javadoc ERROR CODE = %d\n", returnCode);throw new IllegalStateException();}} catch (Throwable e) {e.printStackTrace();fail();}}public static class DocletExample implements Doclet {private Reporter reporter;private Elements elementUtils;@Overridepublic 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) {reporter.print(Kind.NOTE, "Element " + e.getKind() + ": "+ e);// 输出对应的注解reporter.print(Kind.NOTE,elementUtils.getDocComment(e));}}@Overridepublic boolean run(DocletEnvironment docEnv) {// get the DocTrees utility class to access document commentsDocTrees docTrees = docEnv.getDocTrees();elementUtils = docEnv.getElementUtils();// 循环调用printElement输出每个类成员的注释for (TypeElement t : ElementFilter.typesIn(docEnv.getIncludedElements())) {reporter.print(Kind.NOTE, t.getKind() + ":" + t.getQualifiedName());if(t.getQualifiedName().toString().endsWith("ResourcePool")) {reporter.print(Kind.NOTE, "ResourcePool");}reporter.print(Kind.NOTE, "getDocComment:"+elementUtils.getDocComment(t));	            for (Element e : t.getEnclosedElements()) {printElement(docTrees, e);}}return true;}@Overridepublic String getName() {return "DocletExample";}@Overridepublic Set<? extends Option> getSupportedOptions() {Option[] options = {};return Set.of(options);}@Overridepublic SourceVersion getSupportedSourceVersion() {// support the latest releasereturn SourceVersion.latest();}}
}