Question

I really like the way Eclipse has pop-up Javadoc documentation for the various Java library classes I use. However, I also use JPA and JAXB annotations such as @Entity and @XMLType. Eclipse recognises these as valid because I can hit ctrl-space and they pop-up. I also get Javadoc for javax classes.

But there is no Javadoc for these annotations…it just reports that Javadoc could not be found.

I’ve downloaded the javadoc, installed it on my system and associated with all the JARs in my Java6 system library (the only one installed).

Any ideas? Hard to believe there is no Javadoc on annotations!

Answer 1

@Entity isn’t marked with the @Documented annotation.

@Target(TYPE) 
@Retention(RUNTIME)
public @interface Entity {

If you try with the @javax.Inject annotation instead, you should see the JavaDoc, since it’s marked with @Documented.

@Target({ METHOD, CONSTRUCTOR, FIELD })
@Retention(RUNTIME)
@Documented
public @interface Inject {}

The @Documented annotation with JavaDoc:

/**
 * Indicates that annotations with a type are to be documented by javadoc
 * and similar tools by default.  This type should be used to annotate the 
 * declarations of types whose annotations affect the use of annotated
 * elements by their clients.  If a type declaration is annotated with
 * Documented, its annotations become part of the public API
 * of the annotated elements.
 *
 * @author  Joshua Bloch
 * @version 1.6, 11/17/05
 * @since 1.5
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Documented {
}

A solution is to import the Java source instead of the JavaDoc. Then it will work as you expect.