Creating Reference Material

Author: MJ Carreon

Source code reference materials are usually the first reports configured for a new project, because it is often of interest to the end user of a library or framework, as well as to the developer of the project itself.

The two reports this section illustrates are:

  • JXR – the Java source cross reference, and,
  • Javadoc – the Java documentation tool

You can get started with JXR on the example project very quickly, by running the following command:

C:\mvnbook\proficio\proficio-core> mvn jxr:jxr

You should now see a target/site/xref/index.html created.

 

Figure 6-6: An example source code cross reference

Figure 6-6 shows an example of the cross reference. Those familiar with Javadoc will recognize the framed navigation layout, however the content pane is now replaced with a syntax-highlighted, cross-referenced Java source file for the selected class. The hyper links in the content pane can be used to navigate to other classes and interfaces within the cross reference.

A useful way to leverage the cross reference is to use the links given for each line number in a source file to point team mates at a particular piece of code. Or, if you don’t have the project open in your IDE, the links can be used to quickly find the source belonging to a particular exception.

Including JXR as a permanent fixture of the site for the project is simple, and can be done by adding the following to proficio/pom.xml:

[...]
<reporting>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-jxr-plugin</artifactId>
    </plugin>
    [...]
  </plugins>
</reporting>
[...]

You can now run mvn site in proficio-core and see target/site/project-reports.html created. This page contains the Source Xref and the Test Source Xref items listed in the _Project Reports _menu of the generated site.

In most cases, the default JXR configuration is sufficient, however if you’d like a list of available configuration options, see the plugin reference here.

Note: A Javadoc report is only as good as your Javadoc! Make sure you document the methods you intend to display in the report, and if possible use Checkstyle to ensure they are documented.

Using Javadoc is very similar to the JXR report and most other reports in Maven. Again, you can run it on its own using the following command:

C:\mvnbook\proficio\proficio-core> mvn javadoc:javadoc

Since it will be included as part of the project site, you should include it in proficio/pom.xml as a site report to ensure it is run every time the site is regenerated:

[...]
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
</plugin>
[...]

The end result is the familiar Javadoc output, in target/site/apidocs.

Unlike JXR, the Javadoc report is quite configurable, with most of the command line options of the Javadoc tool available.

One useful option to configure is links. In the online mode, this will link to an external Javadoc reference at a given URL.

For example, the following configuration, when added to proficio/pom.xml, will link both the JDK 1.5 API documentation and the Plexus container API documentation used by Proficio:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <configuration>
    <links>
      <link>http://java.sun.com/j2se/1.5.0/docs/api</link>
      <link>http://plexus.codehaus.org/ref/1.0-alpha-9/apidocs</link>
    </links>
  </configuration>
</plugin>

If you regenerate the site in proficio-core with mvn site again, you’ll see that all references to the standard JDK classes such as java.lang.String and java.lang.Object, are linked to API documentation on the Sun Web site, as well as any references to classes in Plexus.

Setting up Javadoc has been very convenient, but it results in a separate set of API documentation for each library in a multi-module build. Since it is preferred to have discrete functional pieces separated into distinct modules, but conversely to have the Javadoc closely related, this is not sufficient.

One option would be to introduce links to the other modules (automatically generated by Maven based on dependencies, of course!), but this would still limit the available classes in the navigation as you hop from module to module. Instead, the Javadoc plugin provides a way to produce a single set of API documentation for the entire project.

Edit the configuration of the existing Javadoc plugin in proficio/pom.xml by adding the following line:

[...]
<configuration>
  <aggregate>true</aggregate>
  [...]
</configuration>
[...]

When built from the top level project, this simple change will produce an aggregated Javadoc and ignore the Javadoc report in the individual modules. This setting must go into the reporting section so that it is used for both reports and if the command is executed separately. However, this setting is always ignored by the javadoc:jar goal, ensuring that the deployed Javadoc corresponds directly to the artifact with which it is deployed for use in an IDE.

Try running mvn clean javadoc:javadoc in the proficio directory to produce the aggregated Javadoc in target/site/apidocs/index.html.

Now that the sample application has a complete reference for the source code, the next section will allow you to start monitoring and improving its health.