Creating Reference Material
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:mvnbookproficioproficio-core> mvn jxr:jxr
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
[...] <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.
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:mvnbookproficioproficio-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
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
mvn site again, you’ll see that all references to the standard JDK classes such as
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.
mvn clean javadoc:javadoc in the
proficio directory to produce the aggregated Javadoc in
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.