View RSS Feed

My Java Tips

Adding public documentation

Rate this Entry
by , 10-31-2011 at 06:24 PM (608 Views)
Documented is a meta-annotation and its a marker annotation. A marker annotations have no member variables.


Documented annotation is used to indicate that an annotation should appear in the Javadoc for a class. Remember that the default behavior is that annotations are not included in Javadocs. The presented example shows what the Documented meta-annotation looks like in use:

Java Code:
package com.domain.tiger.a;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

// Using the Documented meta-annotation
/**
 * Marker annotation to indicate that a method or class
 *   is still in progress.
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface InProgress { }
I would recommend you to implement the presented example also.


The one confusion thing with Documented is in the retention policy. The presented example specifies the annotation's retention as RUNTIME. Remember that this is a required aspect of using the Documented annotation type.

An important concept to remember is that Javadoc loads its information from class files and not from the source files using a virtual machine. The only way to ensure that this VM gets the information for producing Javadoc from these class files is to specify the retention of Retention Policy.RUNTIME.

Putting it all together: the annotation is kept in the compiled class file and is loaded by the VM. Javadoc then picks it up and adds it to the class's HTML documentation.

Submit "Adding public documentation" to Facebook Submit "Adding public documentation" to Digg Submit "Adding public documentation" to del.icio.us Submit "Adding public documentation" to StumbleUpon Submit "Adding public documentation" to Google

Tags: None Add / Edit Tags
Categories
Annotations

Comments