JavaDoc with Java 5, including Generic Type Parameters, Package comments, and Overview

JavaDoc has changed in a couple of ways, and I thought I would highlight some of those changes. This post also includes a couple of things that aren't changes, but that are probably a good idea to do in your docs.

How to Document Generic Type Parameters
In order to avoid the hassle of introducing a new keyword into Java, Sun chose to use the @param tag to identify generic type parameters for classes
and methods. Here is an example of a class with a class-level type parameter:

/**
* The interface that RulesEngines must adhere to.
*
* @param <T> Indicates that for this instantiation of the engine, the type
* of Rule implementation we want to execute. Because there can be lists of
* different implementations floating around, we want to not force clients
* to cast or extract the kernel rule to be evaluated from their wrapper
* (say, a {@link UserDefinedRule} or any application-specific wrapper). This
* way, they can specify the type parameter and we at least know that the
* engine can reliably fire the rules.
*
* @author E Hewitt
* @see com.dte.rules.engine.SimpleRulesEngine
* @see com.dte.rules.engine.EventHistory
* @since 1.0
*/
public interface RulesEngine<T extends Rule> {

//...

It works the same way for methods:

/**
* Puts a Rule into the Engine, to be extecuted in this session. Every rule
* that has been added to the Engine will be inspected for each object in
* the engine to find matches, unless some directive indicating otherwise
* is returned with the execution result.
*
* @param rule the rule implementation to add. A UserDefinedRule is
* typically the sort of object an end-user would create and save to a
* database for execution later.
* @return a Handle on the Rule so you can get it out later if necessary.
*/
RuleHandle addRule(T rule);

Eclipse automatically inserts these with Ctrl + Space, and NetBeans probably does too, but I don't know.

Changes to Package.html
Package.html is a file used to write general comments about the purpose of a package. While package.html still works in Java 5, there is a new and preferred way to do it now. Instead of writing an HTML file, write a Java source file. Here's how:

1. In the package you want to document, create a file called package-info.java.
2. Use regular Javadoc comments to comment the single line of Java code in the file--the package declaration.

Translate your package.html file to package-info.java files. Here is an example.

package.html:

<html>
<head>
<title>com.dte.rules</title>
</head>
<body>

Provides the classes that client applications will use in
creating rules of their own.


Look at {@link com.dte.rules.Rule}, {@link com.dte.rules.Consequence},
and {@link com.dte.rules.Salience} to get started.

@since 1.0

</body>
</html>

Here is the same file as package-info.java:

/**
* Provides the classes that client applications will use in creating rules
* of their own.
* 
* Look at {@link com.dte.rules.Rule}, {@link com.dte.rules.Consequence},
* and {@link com.dte.rules.Salience} to get started.
*
* @since 1.0
*/
package com.dte.rules;

Note that Eclipse doesn't want you to create a source file with that name, so just create it as a regular File with a .java extension.

Overview.html
Overview.html, like package.html, is used to illustrate the purpose of your project, and provide a starting place to point to further documentation. This actually did not change in Java 5, but not many of our projects here appear to use overview.html, and it is a good idea to use it. So here is how, since we're on the topic:

1. Create a file called overview.html. This should probably be in a directory called "docs" under your project.
The HTML should be simple, and include the name of your project and a brief description of what your project does. Like this:

<html>
<head></head>
<body>
<h1>Rules Engine</h1>

The Rules Engine Project defines and implements an engine capable
of executing a set of business Rules on a set of Facts in order to find
matches, and execute a Consequence on matches, much like an Expert System
such as JESS or a Rules Engine such as JBoss Rules.
</body>
</html>

2. In your Ant task to generate your JavaDoc, add the "overview" attribute to point to your overview.html file. Like this:

The result is that the overview text will be included in the index page of your JavaDoc, above your package listings.

InheritDoc
Also, in case you did not know, you can inherit documentation. If you have a base class or an interface that defines a method that is well commented, you don't have to copy the comments into every implementation. You just just do this:

/**
* {@inheritDoc}
*/

And the complete text of the JavaDoc from the interface or parent class will end up where it should, with the addition of something like this at the end of your comment:

Specified by:
setGlobalContext in interface RulesEngine<T extends Rule>

If you want to add something to the inherited comment that is particular to your implementation, you can do so:

/**
* {@inheritDoc}
* 
* This implementation throws a RuleException if you call it a second time
* before the engine has been released.
*/
public void setGlobalContext(GlobalContext context) {
//....
}

And you'll get both the original comment and your addition.

Including Multiple Projects' JavaDocs in a Single Doc Instance
You may work on large projects that are dependent on totally seperate, external projects. You can include dependent projects' JavaDocs in your main project if you like. I do this for example in the RPM project, which depends on both the Shared project and the Rules Engine project. Just use the group element nested within the javadoc task, like this: