Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

The @Documented annotation is a built-in Java meta-annotation that instructs the Javadoc tool to include the target annotation in the generated public API documentation. By default, Java annotations are omitted from generated documentation. Applying @Documented to a custom annotation declaration overrides this default behavior, ensuring that any element annotated with the custom annotation will display that annotation in its documented signature. Located in the java.lang.annotation package, @Documented is a marker annotation, meaning it contains no elements or methods. It is strictly used as a meta-annotation, meaning its target is restricted to other annotation interfaces (ElementType.ANNOTATION_TYPE).

​
Syntax and Application

To utilize @Documented, it must be placed directly above the declaration of a custom annotation: 
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Documented
@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.TYPE)
public @interface ThreadSafe {
    String author() default "";
}

​
Documentation Generation Mechanics

When the javadoc utility processes source code, it evaluates the meta-annotations of all annotations present on the source elements. Because the javadoc tool parses source code directly using the Compiler API, it is fully capable of reading and documenting annotations regardless of their RetentionPolicy. There is no minimum retention policy requirement; annotations with RetentionPolicy.SOURCE are processed just as effectively as those with CLASS or RUNTIME. Given the @ThreadSafe annotation defined above, if it is applied to a class: 
@ThreadSafe(author = "CoreArchitectureTeam")
public class ConnectionPool {
    // Class implementation
}
The resulting Javadoc HTML for ConnectionPool will explicitly render the annotation in the class signature: 
@ThreadSafe(author="CoreArchitectureTeam")
public class ConnectionPool
extends Object
If the @Documented meta-annotation were omitted from the ThreadSafe declaration, the Javadoc tool would strip the annotation during generation. The documented signature would then simply read: 
public class ConnectionPool
extends Object

​
Internal Definition

The Java standard library defines @Documented as follows: 
package java.lang.annotation;

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Documented {
}
Because @Documented is self-annotated, its presence is visible in its own official Java API documentation. While @Documented itself is declared with RetentionPolicy.RUNTIME (allowing it to be inspected via reflection), this is a property of the meta-annotation itself, not a requirement it imposes on the annotations it targets.
Master Java with Deep Grasping Methodology!Learn More