The Documented Annotation

The Documented annotation indicates that an annotation with this type should be documented by the Javadoc tool. Javadoc is a documentation generator provided as a part of the JDK that helps in generating API documentation in HTML format from Java source code.  As we already know that we use /** … */ for commenting the code. This is a Javadoc comment.

Javadoc defines several tags, such as

·         @author

·         @version

·         @param

·         @return,

·         and so on.

 We use these tags to describe the corresponding elements.

By default, the Javadoc tool includes annotations in the generated document. Applying the @Documented annotation allows Javadoc-like tools to include the annotation type information in the generated documentation. Incidentally, this is a Marker-type annotation because it does not have any members. To understand how this works, add the @Documented annotation to the WorkInProgress and Task annotations we have created pin the previous post (Annotations at Runtime). Now, generate the documentation for the RuntimeAnnotation class by executing the following command on the command prompt:

c:\360\annotaion>javadoc RuntimeAnnotation.java

Executing this javadoc command will generate quite a few HTML files in the current folder. Open the index.html file in your favorite browser and examine the documentation for the ComputeTax method, which uses both annotations.

The Inherited Annotation

When a class is inherited, the subclass inherits all the non-private properties of its superclass. Does this happen in the case of annotations too? In other words, if a class is annotated, are the annotations of the parent class inherited by the subclass?

Let’s look at an example. Suppose we have a class called Shape that implements a few drawing primitives. The Shape class is not yet fully implemented, so we add the @WorkInProgress annotation we have been using so far. We’ll now extend the Shape class to create a Line class. We would naturally expect and want the Line class to inherit the WorkInProgress annotation because this class is yet to be implemented.

Does this happen naturally? No, this inheritance takes place only if the WorkInProgress annotation is annotated with @Inherited.

Program Code

To better understand this concept, let’s look at the program here:

import java.lang.annotation.*;

@WorkInProgress
class Shape {
                     public void drawShape() {

                     }

}

public class drawShape extends Shape {
                     @Override
                     public void drawShape() {

                     }

                     public static void main(String[] args) {
                             Shape shape = new Shape();
                             Class cls = shape.getClass();

                             if (cls.isAnnotationPresent(WorkInProgress.class)) {
                                      System.out.println("Shape class does require some work");
                                      WorkInProgress progress = (WorkInProgress) cls
                                                          .getAnnotation(WorkInProgress.class);
                                      System.out.println(progress.doSomething());

                             } else {

                                      System.out.println("Shape is fully implemented");
                             }
                             System.out.println();
                             drawShape line = new drawShape();
                             cls = line.getClass();

                             if (cls.isAnnotationPresent(WorkInProgress.class)) {
                                      System.out.println("Line class does require some work");
                                       WorkInProgress progress = (WorkInProgress) cls
                                                          .getAnnotation(WorkInProgress.class);

                                      System.out.println(progress.doSomething());

                             } else {
                                      System.out.println("Line is fully implemented");

                             }
                             System.out.println();

                     }

}
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
@interface WorkInProgress {
                     String doSomething() default "\tDo what?";

}

Shape class does require some work

                Do what?

Line class does require some work

                 Do what?

Shape class does require some work
              Do what?
Line is fully implemented