src/site/apt/examples/alternate-doclet.apt.vm

 ------
 Using Alternate Doclet
 ------
 Vincent Siveton
 Maria Odea Ching
 ------
 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

Using Alternate Doclet

 To generate output from an alternate doclet, add configuration similar to the following to your POM.

 In this example, the doclet is UmlGraph ({{http://www.umlgraph.org/}}). UmlGraph allows the declarative specification
 and drawing of UML class and sequence diagrams.

 <<Note about UmlGraph>>: You must have the Graphviz binary in your PATH, or the images will not be generated.
 For more information about Graphviz, please refer to {{http://www.graphviz.org/}}.

+-----+
<project>
  ...
  <reporting> (or <build>)
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <doclet>org.umlgraph.doclet.UmlGraphDoc</doclet>

          <!-- <docletPath>/path/to/UmlGraph.jar</docletPath> -->
          <docletArtifact>
            <groupId>org.umlgraph</groupId>
            <artifactId>doclet</artifactId>
            <version>5.1</version>
          </docletArtifact>
          <additionalOptions>
            <additionalOption>-views</additionalOption>
          </additionalOptions>
        </configuration>
      </plugin>
    ...
    </plugins>
  </reporting> (or </build>)
  ...
</project>
+-----+

 <<Note>>:

   * {{{../javadoc-mojo.html#additionalOptions}\<additionalOptions/\>}} parameter could be used to set additional
   parameters on the command line, specifically for doclet options.

   * {{{../javadoc-mojo.html#useStandardDocletOptions}\<useStandardDocletOptions/\>}} parameter could be used to specify
   that the given doclet should use the
   {{{http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#standard}options provided by the Standard Doclet}}.

   * If you need more artifacts in the docletpath, you could use the
   {{{../javadoc-mojo.html#docletArtifacts}\<docletArtifacts/\>}} parameter.

   []

 After executing <<<mvn site>>>, you will see that a UML graph (.dot file) will be generated in the
 destination directory.

Using Alternate Doclet In Addition To The Javadoc Doclet

 To generate output from an alternate doclet in addition to the normal HTML Javadoc doclet, add configuration
 similar to the following to your POM.

 In this example, the doclet is Sun DocCheck ({{http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html/}}). The Sun Doc Check Doclet
 is an extension to the Javadoc tool. It runs on source code and reviews documentation comments, generating an HTML
 report that identifies empty comments and other ommissions and irregularities in the documentation comments.

+-----+
<project>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>${project.version}</version>
        <reportSets>
          <reportSet>
            <id>html</id>
            <reports>
              <report>javadoc</report>
            </reports>
          </reportSet>
          <reportSet>
            <id>doccheck</id>
            <configuration>
              <doclet>com.sun.tools.doclets.doccheck.DocCheck</doclet>

              <!-- <docletPath>/path/to/doccheck.jar</docletPath> -->
              <docletArtifact>
                <groupId>com.sun.tools.doclets</groupId>
                <artifactId>doccheck</artifactId>
                <version>1.2b2</version>
              </docletArtifact>
              <additionalOptions>
                <additionalOption>-d</additionalOption>
                <additionalOption>\${project.build.directory}/site/doccheck</additionalOption>
              </additionalOptions>

              <!-- Other dir than apidocs -->
              <destDir>doccheck</destDir>

              <!-- For the project-reports page-->
              <name>DocCheck</name>
              <description>DocCheck documentation.</description>
            </configuration>
            <reports>
              <report>javadoc</report>
            </reports>
          </reportSet>
        </reportSets>
      </plugin>
      ...
    </plugins>
  </reporting>
  ...
</project>
+-----+