Java 1.5 Tiger A Developers Notebook [Electronic resources] نسخه متنی

6.9 Documenting Annotation Types

Annotations are a
nice addition, and are a particularly cool feature if you
need to troubleshoot, update, or maintain code that was written by
someone else. It also makes for a killer code-level management system
on open source projects. In "Creating Custom Annotation Types," I developed
very simple annotation typesInProgress, TODO, and GroupTODOthat would all function in that sort of environment. While these are great
if you're actually scanning source code, they aren't visible in the code's
Javadoc. This is where the Documented meta-annotation comes into play.
You can use it to ensure your annotations show up in generated Javadoc.

NOTE

If you're using the
supplied Ant
buildfile, use "ant
Javadoc" to
generate
Javadoc.

6.9.1 How do I do that?

First, to understand what detail you are missing without using
Documented, generate Javadoc for the source code of this book. Pull up
those API docs, and navigate to the com.oreilly.tiger.ch06 package,
and then the AnnotationTester class. Scroll down, if needed, to the
calculateInterest( ) methodyou should see something similar to
Figure 6-1.

Figure 6-1. calculateInterest( ) without documentation of annotations

Nothing special, right? Rightbut there's something missing. Remember
the code for this method:

     @com.oreilly.tiger.ch06.InProgress
@GroupTODO(
severity=GroupTODO.Severity.CRITICAL,
item="Figure out the amount of interest per month",
assignedTo="Brett McLaughlin",
dateAssigned="04-26-2004"
)
public void calculateInterest(float amount, float rate) {
// Need to finish this method later
}

While the source code contains some pretty important information, in the
form of the InProgress and GroupTODO annotations, this information
missing from the Javadoc.

To fix this, you need to add a @Documented meta-annotation to any annotation
type that you want to appear in Javadoc. In this case, both
InProgress and GroupTODO, as well as TODO, could use this addition.
Example 6-12 shows an updated InProgress; you can add the same
lines to the other annotation types.

Example 6-12. Adding documentation to InProgress

package com.oreilly.tiger.ch06;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
/**
* Marker annotation to indicate that a method or class
*   is still in progress.
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface InProgress { }

I've also added the Retention meta-annotation to this class; anytime you
use the Documented annotation, you should pair it with a retention policy
of RetentionPolicy.RUNTIME. Make this same change to the other annotation
types defined in com.oreilly.tiger.ch03.

Clean out your old Javadoc files. Now, recompile your classes and run the
Javadoc generator again. This time, you'll get a bit different outputnavigate
again to com.oreilly.tiger.ch06, and then AnnotationTester, and
finally to the calculateInterest( ) method. Figure 6-2 shows the same
method, but this time the annotations show up in the Javadoc.

NOTE

"ant clean" will
remove all
compiled class
files, and
Javadoc files,
allowing a clean
generation of
Javadoc.

Figure 6-2. Javadoc with annotations showing up