> ## 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.
# Java Documented Annotation
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:
```java theme={"dark"}
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:
```java theme={"dark"}
@ThreadSafe(author = "CoreArchitectureTeam")
public class ConnectionPool {
// Class implementation
}
```
The resulting Javadoc HTML for `ConnectionPool` will explicitly render the annotation in the class signature:
```text theme={"dark"}
@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:
```text theme={"dark"}
public class ConnectionPool
extends Object
```
## Internal Definition
The Java standard library defines `@Documented` as follows:
```java theme={"dark"}
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.
Tired of Poor Java Skills? Fix That With Deep Grasping!
Learn More
