如何检查Java库中的Javadoc注释？

因为Javadoc注释是从源码中提取生成的，所以**必须基于lib-sources.jar（源码包）**来做检查，lib-javadoc.jar是生成好的静态站点，无法用于规则校验。下面是几种实用的检查方式：

1. 用Javadoc官方工具自带校验 #

Javadoc命令本身就支持Javadoc规范检查，步骤如下：

• 先解压源码包到本地目录：

  unzip lib-sources.jar -d src-dir
  

• 运行带校验参数的Javadoc命令，启用所有规范检查（包括@param/@return缺失等）：

  javadoc -d ./temp-javadoc -sourcepath ./src-dir -subpackages 你的包路径（比如com.example.lib） -Xdoclint:all
  

  执行后，控制台会直接输出所有不符合规范的问题，比如缺失的@param、@return标签，或者格式错误的注释。

2. 用Checkstyle静态代码分析工具 #

Checkstyle可以自定义Javadoc检查规则，灵活性更高：

• 解压源码包到本地目录
• 下载Checkstyle的可执行jar包，编写配置文件（比如checkstyle-config.xml），启用需要的Javadoc规则：

  <?xml version="1.0"?>
  <!DOCTYPE module PUBLIC
          "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
          "https://checkstyle.org/dtds/configuration_1_3.dtd">
  <module name="Checker">
      <module name="TreeWalker">
          <!-- 检查方法参数是否有@param注释 -->
          <module name="JavadocParameter"/>
          <!-- 检查非void方法是否有@return注释，以及方法Javadoc完整性 -->
          <module name="JavadocMethod"/>
          <!-- 检查类/接口的Javadoc注释 -->
          <module name="JavadocType"/>
      </module>
  </module>
  

• 运行Checkstyle命令扫描源码：

  java -jar checkstyle.jar -c checkstyle-config.xml ./src-dir
  

  工具会输出所有违反规则的代码位置和问题描述。

3. 用IDE内置检查功能 #

主流IDE都自带Javadoc规范检查，适合可视化排查：

• 将解压后的源码导入IntelliJ IDEA或Eclipse
• IntelliJ IDEA：
  1. 打开Settings → Inspections → Java → Javadoc
  2. 勾选需要检查的项（比如Missing @param tag、Missing @return tag）
  3. 执行Analyze → Inspect Code，IDE会列出所有不符合规范的位置
• Eclipse：
  1. 打开Preferences → Java → Compiler → Javadoc
  2. 勾选对应的警告/错误选项（比如Missing Javadoc for parameters、Missing Javadoc for return type）
  3. 项目会自动在代码中标注出问题位置

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