修复 Javadoc 注释

当开发人员编写代码时，他们可能会忘记创建（或更新）Javadoc 注释。fix和test-fix目标是交互式目标（即通常在命令行中使用），用于修复类中的实际 Javadoc 注释。

您需要调用mvn javadoc:fix来修复主要 Java 源文件（即在 src/main/java 目录中）或调用 mvn javadoc :test-fix来修复测试 Java 源文件（即在 src/test/java 目录中）。

重要提示：由于更改是直接在源代码中完成的，我们强烈建议使用 SCM，因此如果出现问题，您可以随时进行还原。您始终可以添加-DoutputDirectory=/path/to/dir来指定将生成类的目标目录。

功能总结

用户可以使用特定参数（即<fixClassComment/> ）跳过类/字段/方法 Javadoc 修复。此外，用户可以指定一个<level/>，即公共，以仅修复具有给定级别的类/字段/方法。

这些目标可以动态地修复所有 Javadoc 标签（默认情况下，请参阅<fixTags/>）或选择性标签，如作者、版本......此外，用户可以为某些标签指定默认值，即<defaultAuthor/>。

javadoc:fix目标可以使用Clirr (通过clirr-maven-plugin，一个检查 Java 库与旧版本的二进制和源代码兼容性的工具。因此，@since标记将为当前项目版本动态添加。您需要添加compareVersion参数（见下文）。

最后，用户可以使用包含/排除参数处理特定的 Java 文件。

当前限制

修复和测试修复目标大量使用Qdox从源文件中提取类/接口/方法 Javadoc。不幸的是，Qdox 有一些已知问题。

示例调用

mvn javadoc:fix -DcomparisonVersion=1.0
...
[INFO] [javadoc:fix]
[WARNING]
[WARNING]     WARRANTY DISCLAIMER
[WARNING]
[WARNING] All warranties with regard to this Maven goal are disclaimed!
[WARNING] The changes will be done directly in the source code.
[WARNING] The Maven Team strongly recommends the use of a SCM software BEFORE executing this goal.
[WARNING]
[INFO] Are you sure to proceed? [Y]es [N]o
y
[INFO] OK, let's proceed...
[INFO] Clirr output file was created: target/clirr.txt
[INFO] Clirr found API differences, i.e. new classes/interfaces or methods.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
...

您可以查看更改并提交。

使用 Clirr 集成

注意：应首先部署以前的工件。

与特定版本比较

默认情况下，目标将当前代码与低于当前版本的最新发布版本进行比较。如果你想使用其他版本，你需要指定它类似于 Maven Clirr Plugin：

mvn javadoc:fix -DcomparisonVersion=1.0
...
[INFO] Clirr output file was created: target/clirr.txt
[INFO] Clirr found API differences, i.e. new classes/interfaces or methods.
...

使用另一个 Clirr 版本

默认情况下，修复和测试修复目标使用clirr-maven-plugin版本2.2.2。要使用其他版本，需要在 Javadoc 插件中添加依赖项，类似于以下内容：

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.3.2</version>
        <configuration>
            ...
        </configuration>
        <dependencies>
          <dependency>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>clirr-maven-plugin</artifactId>
            <version>2.3-SNAPSHOT</version>
          </dependency>
        </dependencies>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>