javdoc:(JDK9)VISITOR模式遍历语法树(DocCommentTree)获取代码注释中的tag(@return,@param)对象

🕗 发布于 2024-09-26 13:55 java javadoc jdk9 访问者模式 DocCommentTree

上一篇博客《javadoc:jdk 9通过javadoc API读取java源码中的注释信息(comment)》介绍了JDK9下javadoc API的基本使用方法。
本文进一步示例说明如何通过使用遍历语法树的方式更精确获取注释对象中子对象的方法。

DocCommentTree

JDK9 的Javadoc API可以语法树的形式提供解析后的注释对象DocCommentTree

以下是通过Doclet获取DocCommentTree并输出的代码片段，

代码取自
https://download.java.net/java/early_access/valhalla/docs/api/jdk.javadoc/jdk/javadoc/doclet/package-summary.html#example-heading

public class Example implements Doclet {
    public void printElement(DocTrees trees, Element e) {
    /** 从 DocTrees 中获取对应类型的注释语法树 */
        DocCommentTree docCommentTree = trees.getDocCommentTree(e);
        if (docCommentTree != null) {
            stdout.println("Element (" + e.getKind() + ": "
                    + e + ") has the following comments:");
            /** 输出注释内容 */
            stdout.println("Entire body: " + docCommentTree.getFullBody());
            /** 输出注释中块标签，例如 @return,@param,@throws */
            stdout.println("Block tags: " + docCommentTree.getBlockTags());
        }
    }

    @Override
    public boolean run(DocletEnvironment docEnv) {
        // 获取DocTrees实用程序类以访问文档注释
        DocTrees docTrees = docEnv.getDocTrees();
/** 循环调用printElement输出所有类的注释 */
        for (TypeElement t : ElementFilter.typesIn(docEnv.getIncludedElements())) {
            stdout.println(t.getKind() + ":" + t);
            for (Element e : t.getEnclosedElements()) {
                printElement(docTrees, e);
            }
        }
        return true;
    }
}

从上面的代码可以理解 DocCommentTree对象代表了一个类、方法、成员的对应的结构化注释数据，DocCommentTree.getFullBody()返回注释内容，DocCommentTree.getBlockTags()返回注释中块标签对象列表，例如 @return,@param,@throws

在DocCommentTree对象的基础上，我们就可以自由地获取一个注释对象的所有细节。

DocTreeVisitor

所有注释对象（包括DocCommentTree）都实现了com.sun.source.doctree.DocTree接口。
JDK 9提供了com.sun.source.doctree.DocTreeVisitor接口,用于以VISITOR模式遍历 DocTree对象。以实现对注释对象的自由处理。
为了理解DocTreeVisitor接口的作用和用法，我觉得最直接的方式就是看它的一个实现com.sun.tools.javac.tree.DocPretty，这个类实现了对一个DocTree的打印输出到java.io.Writer,

所有DocTree实现的toString()方法都是用这个DocPretty输出为String。

如下是所有DocTree接口的实现的基类com.sun.tools.javac.tree.DCTree 的代码片段：

public abstract class DCTree implements DocTree {
    /**
     * Convert a tree to a pretty-printed string.
     */
    @Override
    public String toString() {
        StringWriter s = new StringWriter();
        try {
            new DocPretty(s).print(this);
        }
        catch (IOException e) {
            // should never happen, because StringWriter is defined
            // never to throw any IOExceptions
            throw new AssertionError(e);
        }
        return s.toString();
    }
}

SimpleDocTreeVisitor

话说DocTreeVisitor接口有十几个方法，如果要全部自己实现，要写太多代码了。
其实一般不需要这么做。因为JDK 9同时还提供了com.sun.source.util.SimpleDocTreeVisitor方法实现了DocTreeVisitor所有方法。对于调用者来说，继承SimpleDocTreeVisitor类，根据需要重写特定的方法，才是一般场景的DocTreeVisitor的实现方式。

JDK 9提供的另一个DocTreeVisitor实现com.sun.source.util.DocTreeScanner也建议看一下，DocTreeScanner偏向于遍历所有子节点，调用者根据自己需要，决定使用哪个做基类。

在本文中，我们需要实现遍历DocCommentTree所有的BlockTagTree。所以选择SimpleDocTreeVisitor作为基类。因为SimpleDocTreeVisitor所有默认方法实现都调用SimpleDocTreeVisitor.defaultAction方法，只要重写defaultAction方法，就可以实现所有块标签类型判断。程序逻辑要简单很多。

BlockTagExtracter

以下是继承SimpleDocTreeVisitor实现DocTreeVisitor接口的代码。作用很简单，当输入遍历对象是DocCommentTree 时将，所有对象中的所有块标签(block tag)对象保存到一个Map,以供后续使用。
BlockTagExtracter.java


import java.util.LinkedHashSet;
import java.util.Set;

import com.google.common.collect.Maps;
import com.google.common.collect.Multimaps;
import com.google.common.collect.SetMultimap;
import com.sun.source.doctree.*;
import com.sun.source.util.SimpleDocTreeVisitor;

/**
 * 读取所有注释标签({@link BlockTagTree})，如：'@author','@param',保存到{@link #blockTags}
 */
class BlockTagExtracter extends SimpleDocTreeVisitor<Void,Void> {
/** 保存块标签(block tag)的MultiMap（允许Key重复） */
private final SetMultimap<String, BlockTagTree> blockTags = Multimaps.newSetMultimap(Maps.newLinkedHashMap(),
LinkedHashSet::new);

    BlockTagExtracter() {
    }
public Set<String> allTags() {
return blockTags.keySet();
}
    @Override
protected Void defaultAction(DocTree node, Void p) {
    if(node instanceof BlockTagTree) {
    /** 如果是块标签，则保存到blockTags */
    blockTags.put("@"+ node.getKind().tagName, (BlockTagTree) node);
    }
return super.defaultAction(node, p);
}

@Override 
    public Void visitDocComment(DocCommentTree node, Void p) {
    /** 遍历所有 BlockTagTree实例  */
return super.visit(node.getBlockTags(),null);
    }
}

示例

以下为BlockTagExtracter的调用示例代码

import org.junit.Test;
import static org.junit.Assert.*;

import java.util.List;
import java.util.Locale;
import java.util.Set;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
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 {

@Test
public 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",
"-Xdoclint", "none"
});
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;

    @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) {
        reporter.print(Kind.NOTE,"Element " + e.getKind() + ": "
                    + e);
reporter.print(Kind.NOTE,unicodeToString(elementUtils.getDocComment(e)));
        BlockTagExtracter extracter = new BlockTagExtracter();
        /** 遍历 docCommentTree的所有节点 */
        docCommentTree.accept(extracter,null);
        reporter.print(Kind.NOTE,extracter.allTags().toString());
        for(String tag:extracter.allTags()) {
        for(BlockTagTree blockTag: extracter.tags(tag)) {
        reporter.print(Kind.NOTE,unicodeToString(blockTag.toString()));
        }
        }
        }
    }
    /** 将字符串中的unicode转义字符转为unicode字符 */
public static String unicodeToString(String unicodeStr) {
Matcher matcher = Pattern.compile("\\\\u([0-9a-f]{4})").matcher(unicodeStr);
StringBuilder sb = new StringBuilder();
int lastAppendPosition = 0;
while (matcher.find()) {
sb.append(unicodeStr, lastAppendPosition, matcher.start());
sb.append((char) Integer.parseInt(matcher.group(1), 16));
lastAppendPosition = matcher.end();
}
sb.append(unicodeStr, lastAppendPosition, unicodeStr.length());

return sb.toString();
}
    @Override
    public boolean run(DocletEnvironment docEnv) {
        // get the DocTrees utility class to access document comments
        DocTrees docTrees = docEnv.getDocTrees();
        elementUtils = docEnv.getElementUtils();

        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;
    }

    @Override
    public String getName() {
        return "DocletExample";
    }

    @Override
    public Set<? extends Option> getSupportedOptions() {
        Option[] options = {
            new Option() {
                private final List<String> someOption = List.of(
                        "-Xdoclint"
                );

                @Override
                public int getArgumentCount() {
                    return 1;
                }

                @Override
                public String getDescription() {
                    return "Enables recommended checks for problems in Javadoc comments";
                }

                @Override
                public Option.Kind getKind() {
                    return Option.Kind.STANDARD;
                }

                @Override
                public List<String> getNames() {
                    return someOption;
                }

                @Override
                public String getParameters() {
                    return "";
                }

                @Override
                public boolean process(String opt, List<String> arguments) {
                    return true;
                }
            }
        };

        return Set.of(options);
    }

@Override
    public SourceVersion getSupportedSourceVersion() {
        // support the latest release
        return SourceVersion.latest();
    }
}
}

完整代码及示例

完整代码参见码云仓库：https://gitee.com/l0km/javadocreader9

参考资料

《Package jdk.javadoc.doclet》

原文地址：https://blog.csdn.net/10km/article/details/142524176

免责声明：本站文章内容转载自网络资源，如本站内容侵犯了原著者的合法权益，可联系本站删除。更多内容请关注自学内容网（zxcms.com）！

上一篇：直播平台美颜功能开发方案：基于视频美颜SDK的集成详解
下一篇：HTML翻牌器：用CSS和HTML元素创造动态数字展示

leetcode289:生命游戏
根据，简称为，是英国数学家约翰·何顿·康威在 1970 年发明的细胞自动机。给定一个包含m × n个格子的面板，每一个格子都可以看成是一个细胞。每个细胞都具有一个初始状态：1即为（live），或0即为
阅读更多2024-10-20
MongoDB数据恢复
注意：两个MongoDB的版本要一致，本文使用的是mongo:4.2.24。先把K8S上面的MongoDB 容器停止（可以把副本改成0）。1、将容器挂载MongoDB的数据目录备份到本地。经常是数据文
阅读更多2024-10-20
C#中实现事务
C#中实现事务
阅读更多2024-10-20
【LeetCode每日一题】——560.和为 K 的子数组
给你一个整数数组 nums 和一个整数 k ，请你统计并返回该数组中和为 k 的子数组的个数。子数组是数组中元素的连续非空序列。
阅读更多2024-10-20
「漏洞复现」满客宝智慧食堂系统 selectUserByOrgId 未授权访问漏洞
请勿利用文章内的相关技术从事非法测试，由于传播、利用此文所提供的信息而造成的任何直接或者间接的后果及损失，均由使用者本人负责，作者不为此承担任何责任。工具来自网络，安全性自测，如有侵权请联系删除。本次
阅读更多2024-10-20
React面试题目（从基本到高级）
React前端面试常见题目涵盖了React的基础概念、组件、状态管理、生命周期、性能优化等多个方面。
阅读更多2024-10-20
12.个人博客系统（Java项目基于spring和vue）
1 在校学习的学生，可用于日常学习使用或是毕业设计使用 2 毕业一到两年的开发人员，用于锻炼自己的独立功能模块设计能力，增强代码编写能力。 3 亦可以部署为商化项目使用。 4 需要完整资料及源码
阅读更多2024-10-20
YoloV8改进策略：注意力改进|DeBiFormer，可变形双级路由注意力|引入DeBiLevelRoutingAttention注意力模块（全网首发）
本次改进的核心在于将DeBiLevelRoutingAttention模块嵌入到YoloV8的主干网络中，具体位置是在SPPF（Spatial Pyramid Pooling Fast）模块之后。这一
阅读更多2024-10-20
word取消自动单词首字母大写
情况说明：在word输入单词后首字母会自动变成大写取消单词首字母大写步骤：（1）点击菜单栏文件（2）点击“更多”——>“选项”（3）点击“校对”——>“自动更正选项”（4）取消“句首字母大
阅读更多2024-10-20
web前端网页用户注册页面
【代码】web前端网页用户注册页面。
阅读更多2024-10-20