如何在IntelliJ IDEA中检查Javadoc内不当尖括号的使用？

这个问题我之前帮不少开发者解决过——确实挺坑的，本地IDE没提示，到构建平台才炸锅。下面给你几个实用的解决方案，从IDE实时检查到构建阶段拦截全覆盖：

一、开启IntelliJ IDEA的Javadoc语法检查 #

IDEA其实自带相关检查，只是默认可能没开全：

• 打开Settings → Editor → Inspections → 找到Java下的Javadoc分类
• 启用Invalid HTML tag和Unclosed HTML tag这两项检查。它们会扫描Javadoc中的HTML语法问题，未转义的<如果不是合法HTML标签的开头，会被直接标记为错误
• 另外也可以启用Javadoc format检查，它会更全面地校验Javadoc格式规范，包括未转义字符的问题

二、用静态代码分析工具自动检测 #

这类工具能在编码或提交阶段就把问题揪出来：

• Checkstyle：配置JavadocStyle规则，它会严格检查Javadoc中的HTML语法，包括未转义的尖括号。把Checkstyle集成到IDEA或者你的Maven/Gradle构建流程里，就能实时或在构建前检测问题
• SpotBugs：配合JavadocAnnotations相关检测器，也能识别Javadoc中的非法HTML结构，帮你提前发现这类隐藏问题

三、在本地构建阶段提前拦截 #

把Javadoc检查集成到构建流程里，本地构建时就报错，不用等Jitpack：

Maven配置 #

修改pom.xml，启用maven-javadoc-plugin并开启doclint检查：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.5.0</version>
    <executions>
        <execution>
            <id>validate-javadoc</id>
            <phase>verify</phase>
            <goals>
                <goal>javadoc</goal>
            </goals>
            <configuration>
                <doclint>all</doclint>
                <failOnError>true</failOnError>
            </configuration>
        </execution>
    </executions>
</plugin>

这样执行mvn verify时会自动检查Javadoc语法，有问题直接终止构建。

Gradle配置 #

在build.gradle中给javadoc任务添加检查参数：

tasks.withType(Javadoc) {
    options.addStringOption('Xdoclint:all', '-quiet')
    failOnError = true
}

运行gradle javadoc就能触发检查，有错误直接报错。

四、养成规范的Javadoc编写习惯 #

从根源避免问题：

• 遇到<和>时，优先用{@code <...>}包裹，既自动转义，还能保留代码 monospace 样式
• 或者手动转义为<（对应<）和>（对应>）
• 如果用JDK 15+，可以用Javadoc文本块（/** """ 内容 """ */），里面的尖括号不需要转义，写法更直观

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