Maven/Javadoc

Maven Javadoc Plugin

Using an Alternate Doclet

• A more concise explanation of how to configure the UMLGraph doclet is [here.]

• Until Maven Javadoc Plugin 2.0 is released, you will either need to check out and build it from source, or see if there is a recent snapshot available in the repository.

  $ svn checkout http://svn.apache.org/repos/asf/maven/plugins/trunk/ plugins
  $ cd plugins/maven-javadoc-plugin
  $ mvn install

• If you configure multiple <reportSet>s, use the <id> element to identify the separate configurations.

• UMLGraph is not in the central Maven repository and must be downloaded and installed manually
  • http://www.spinellis.gr/sw/umlgraph/
  • The [-views] parameter was new in UMLGraph 4.2.

• The following will generate UMLGraph output in addition to the usual HTML Javadoc:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
   <modelVersion>4.0.0</modelVersion>
   <groupId>net.wsmoak</groupId>
   <artifactId>umlgraph-example</artifactId>
   <packaging>jar</packaging>
   <version>1.0-SNAPSHOT</version>
   <name>UMLGraph Example</name>
   <url>http://wsmoak.net</url>
   <dependencies>
      <dependency>
         <groupId>junit</groupId>
         <artifactId>junit</artifactId>
         <version>3.8.1</version>
         <scope>test</scope>
      </dependency>
   </dependencies>
   <reporting>
      <plugins>
         <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <reportSets>
               <reportSet>
                  <id>uml</id>
                  <configuration>
                     <doclet>gr.spinellis.umlgraph.doclet.UmlGraph</doclet>
                     <docletPath>/path/to/UMLGraph.jar</docletPath-->
                     <docletArtifact>
                        <groupId>umlgraph</groupId>
                        <artifactId>UMLGraph</artifactId>
                        <version>4.3</version>
                     </docletArtifact>
                     <additionalparam>-views</additionalparam>
                     <destDir>target/uml</destDir>
                     <show>private</show>
                  </configuration>
                  <reports>
                     <report>javadoc</report>
                  </reports>
               </reportSet>
               <reportSet>
                  <id>html</id>
                  <configuration>
                     <show>private</show>
                  </configuration>
                  <reports>
                     <report>javadoc</report>
                  </reports>
               </reportSet>
            </reportSets>
         </plugin>
      </plugins>
   </reporting>
</project>

• The following will replace the usual HTML Javadoc with UMLGraph output:

<project>
...
   <build>
      <plugins>
         <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <configuration>
               <doclet>gr.spinellis.umlgraph.doclet.UmlGraph</doclet>
               <!--docletPath>/path/to/UmlGraph.jar</docletPath-->
               <docletArtifact>
                  <groupId>umlgraph</groupId>
                  <artifactId>UMLGraph</artifactId>
                  <version>4.3</version>
               </docletArtifact>
               <additionalparam>-views</additionalparam>
               <destDir>target/uml</destDir>
               <show>private</show>
            </configuration>
         </plugin>
      </plugins>
   </build>

References

• http://jira.codehaus.org/browse/MJAVADOC
• http://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html

Copying Images and Stylesheets

• Not all doclets produce HTML, therefore the plugin should not automatically copy css and images.

• When run with 'mvn javadoc:javadoc' from the <build> section:

~/projects/java/umlgraph-example
$ mvn javadoc:javadoc
  ...

$ ll target/uml
total 12
drwxrwxrwx+ 5 wsmoak None    0 Jan 15 06:32 .
drwxrwxrwx+ 3 wsmoak None    0 Jan 15 06:32 ..
-rwxrwxrwx  1 wsmoak None 2588 Jan 15 06:32 DetailedView.dot
-rwxrwxrwx  1 wsmoak None 2501 Jan 15 06:32 Overview.dot
drwxrwxrwx+ 2 wsmoak None    0 Jan 15 06:32 apidocs
drwxrwxrwx+ 2 wsmoak None    0 Jan 15 06:32 css
drwxrwxrwx+ 3 wsmoak None    0 Jan 15 06:32 images
-rwxrwxrwx  1 wsmoak None 1530 Jan 15 06:32 stylesheet.css

• When run with 'mvn site' from the <reporting> section:

~/projects/java/umlgraph-example
$ mvn site
  ...

$ ll target/site/apidocs
total 12
drwxrwxrwx+ 2 wsmoak None    0 Jan 15 06:47 .
drwxrwxrwx+ 5 wsmoak None    0 Jan 15 06:47 ..
-rwxrwxrwx  1 wsmoak None 2588 Jan 15 06:47 DetailedView.dot
-rwxrwxrwx  1 wsmoak None 2501 Jan 15 06:47 Overview.dot
-rwxrwxrwx  1 wsmoak None 1530 Jan 15 06:47 stylesheet.css

(Note: When running from <reporting>, the <destDir> is ignored, and only the single stylesheet is copied in, not the 'css' and 'images' directories.)

• See: [MJAVADOC-47].