Built by Maven

Fixing Javadoc Comments

When developers write code, they often forget to create (or update) the Javadoc comments. The fix and test-fix goals are interactive goals (i.e. used generally in command line) to fix the actual Javadoc comments in your classes.

You need to call mvn javadoc:fix to fix main Java source files (i.e. inside src/main/java directory) or mvn javadoc:test-fix to fix test Java source files (i.e. inside src/test/java directory).

Important Note: Since the changes are done directly in the source code by default, we strongly recommend using a SCM, so you can revert if a problem occurs. You can also add -DoutputDirectory=/path/to/dir to change the directory where classes will be generated and avoid overwriting the existing source code.

Features Summary

The user can skip the class/field/method Javadoc fixing using specific parameters, i.e. <fixClassComment/>. Also, the user can specify a <level/>, i.e. public, to fix only class/field/method with the given level.

These goals can fix all Javadoc tags (by default, see <fixTags/>) or selective tags like author, version, etc. You specify default value for some tags, for example, <defaultAuthor/>.

The javadoc:fix goal can use Clirr ( via the clirr-maven-plugin to add @since tags will be dynamically added for the current project version. You need to add the comparisonVersion parameter (see below).

Finally, the user can process specific Java files using the includes/excludes parameters.

Current limitations

The fix and test-fix goals use qdox to extract class/interface/method Javadoc from source files.

Example Call

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] ------------------------------------------------------------------------
...

You can then review the changes and commit.

Using Clirr Integration

Comparing against a specific version

By default, the goals compare the current code against the latest released version which is lower than the current version. If you want to use another version, you need to specify it like so:

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.
...

Using another Clirr version

By default, the fix and test-fix goals use the clirr-maven-plugin, version 2.8. To use another version, you need to add a dependency in the Javadoc plugin as shown here:

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