JavaDoc getDocComment()遇元素前置注解失效问题求助

问题场景 #

使用getDocComment()获取变量的Javadoc时，若注释与变量声明之间存在注解，方法会返回null：

正常情况（可正确获取） #

/**
 * A description of varA
 */
private SomeObject varA;

输出：* varA (SomeObject) - A description of varA

异常情况（返回null） #

/**
 * A description of varA
 */
@NotNull
private SomeObject varA;

输出：* varA (SomeObject) -

原因分析 #

根据getDocComment()的官方文档说明：

Returns the text of the documentation ("Javadoc") comment of an element.
A documentation comment of an element is a comment that begins with "/", ends with a separate "/", and immediately precedes the element, ignoring white space. Therefore, a documentation comment contains at least three "" characters. The text returned for the documentation comment is a processed form of the comment as it appears in source code. The leading "/" and trailing "/" are removed. For lines of the comment starting after the initial "/**", leading white space characters are discarded as are any consecutive "" characters appearing after the white space or starting the line. The processed lines are then concatenated together (including line terminators) and returned.

核心限制是：Javadoc必须直接前置目标元素，仅忽略空白字符，注解不属于空白范畴，因此插入注解后，注释不再被认定为变量的关联Javadoc，导致返回null。

解决办法 #

方法1：使用Java Compiler Tree API溯源查找 #

通过JDK自带的com.sun.source.tree包，遍历语法树节点，跳过注解节点后向前查找Javadoc注释：

import com.sun.source.tree.*;
import com.sun.source.util.*;
import java.util.List;

public class DocCommentResolver {
    public static String getVariableDocComment(VariableTree varNode, CompilationUnitTree unit) {
        // 先尝试直接获取
        Comment comment = unit.getComment(varNode);
        if (comment != null && comment.getKind() == Comment.Kind.JAVADOC) {
            return processDocText(comment.getText());
        }

        // 向前遍历成员，跳过注解找Javadoc
        Tree parent = varNode.getParent();
        if (parent instanceof ClassTree) {
            List<? extends Tree> members = ((ClassTree) parent).getMembers();
            int varIndex = members.indexOf(varNode);
            for (int i = varIndex - 1; i >= 0; i--) {
                Tree prevNode = members.get(i);
                if (prevNode instanceof AnnotationTree) {
                    comment = unit.getComment(prevNode);
                    if (comment != null && comment.getKind() == Comment.Kind.JAVADOC) {
                        return processDocText(comment.getText());
                    }
                } else {
                    // 遇到非注解节点，停止查找
                    break;
                }
            }
        }
        return null;
    }

    // 处理Javadoc文本，去掉格式标记
    private static String processDocText(String rawText) {
        return rawText.replaceFirst("/\\*\\*", "")
                      .replaceFirst("\\*/", "")
                      .trim()
                      .replaceAll("^\\s*\\*\\s?", "")
                      .replaceAll("\\n\\s*\\*\\s?", "\n");
    }
}

方法2：借助字节码操作库（如ASM） #

ASM在处理类字节流时，会按顺序读取注释、注解、字段信息，可以缓存遇到的Javadoc，遇到字段时直接关联：

import org.objectweb.asm.*;

public class FieldDocVisitor extends ClassVisitor {
    private String currentDoc;

    public FieldDocVisitor(ClassVisitor cv) {
        super(Opcodes.ASM9, cv);
    }

    @Override
    public void visitField(int access, String name, String descriptor, String signature, Object value) {
        // 当前字段的Javadoc就是缓存的内容
        System.out.printf("* `%s` (%s) - %s%n", name, Type.getType(descriptor).getClassName(), currentDoc);
        // 处理完字段后清空缓存
        currentDoc = null;
        super.visitField(access, name, descriptor, signature, value);
    }

    @Override
    public void visitAttribute(Attribute attr) {
        if (attr instanceof Comment) {
            currentDoc = processDocText(((Comment) attr).getText());
        }
        super.visitAttribute(attr);
    }

    private String processDocText(String rawText) {
        // 同Tree API的格式处理逻辑
        return rawText.replaceFirst("/\\*\\*", "")
                      .replaceFirst("\\*/", "")
                      .trim()
                      .replaceAll("^\\s*\\*\\s?", "")
                      .replaceAll("\\n\\s*\\*\\s?", "\n");
    }
}

总结 #

getDocComment()的设计决定了它无法跨越注解关联Javadoc，必须通过语法树遍历或字节码分析的方式，手动跳过注解节点溯源查找注释，才能解决这个问题。

内容的提问来源于stack exchange，提问作者Tom Delebo