src/site/apt/examples/fix-javadocs.apt.vm

 ------
 Fixing Javadoc Comments
 ------
 Vincent Siveton
 ------
 2009-08-04
 ------

~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html

Fixing Javadoc Comments

 When developers write code, they could 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, we recommend <<strongly>> the use of
 a SCM, so you could always do a revert if a problem occurs. You could always add <<<-DoutputDirectory=/path/to/dir>>>
 to specify a target directory where classes will be generated.

* Features Summary

 The user could skip the class/field/method Javadoc fixing using specific parameters, i.e.
 {{{../fix-mojo.html#fixClassComment}\<fixClassComment/\>}}.
 Also, the user could specify a {{{../fix-mojo.html#level}\<level/\>}}, i.e. public, to fix only class/field/method with
 the given level.

 These goals could fix dynamically all Javadoc tags (by default, see {{{../fix-mojo.html#fixTags}\<fixTags/\>}}) or
 selective tags like author, version...
 Also, the user could specify default value for some tags, i.e. {{{../fix-mojo.html#defaultAuthor}\<defaultAuthor/\>}}.

 The <javadoc:fix> goal could use Clirr ({{{http://clirr.sourceforge.net}}} via the
 {{{http://mojo.codehaus.org/clirr-maven-plugin/}clirr-maven-plugin}}, a tool that checks Java libraries for
 binary and source compatibility with older releases. So, the <@since> tags will be dynamically added for the current
 project version. You need to add the <comparisonVersion> parameter (see below).

 Finally, the user could process specific Java files using the
 {{{../fix-mojo.html#includes}includes}}/{{{../fix-mojo.html#excludes}excludes}} parameters.

** Current limitations

 The <fix> and <test-fix> goals use intensively {{{http://qdox.codehaus.org/}Qdox}} to extract class/interface/method
 Javadoc from source files. Unfortunately, Qdox has {{{https://issues.apache.org/jira/browse/QDOX}some known issues}}.

* 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 could review the changes and commit.

* Using Clirr Integration

  <<Note>>: a previous artifact should be deployed firstly.

** 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 similar to the 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.
...
+-----+

** Using another Clirr version

  By default, the <fix> and <test-fix> goals use the {{{http://mojo.codehaus.org/clirr-maven-plugin/}clirr-maven-plugin}},
  version <<<2.2.2>>>. To use another version, you need to add a dependency in the Javadoc plugin, similar to the
  following:

+-----+
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>${project.version}</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>
+-----+