@Documented - Metadata annotation

TL;DR: @Documented chỉ hõ trợ viết docs - tài liệu public API. Hầu như thói quen của 90% dev không viết docs bằng Javadoc nên có thể bỏ qua bài viết này.

1. Metadata và Meta-annotation

Trong Java, annotation là một dạng metadata — thông tin mô tả bổ sung cho code.

Meta-annotation là annotation dùng để mô tả một annotation khác.

@Documented
@Retention(RUNTIME)
@Target(TYPE)
public @interface MyAnnotation {
}

Ở đây:

• @MyAnnotation → annotation dùng trên class.
• @Documented, @Retention, @Target → meta-annotation của @MyAnnotation.

---

2. @Documented dùng để làm gì?

@Documented
public @interface MyAnnotation {
}

@Documented nói với Javadoc rằng annotation này nên được hiển thị trong documentation.

Nếu không có @Documented, annotation sẽ không được Javadoc đưa vào documentation mặc định.

Vì vậy, @Documented thường được dùng cho annotation thuộc public API, khi người dùng cần biết annotation đó tồn tại và có ý nghĩa gì.

---

3. Tại sao @Documented lại tự annotate chính nó?

Source của JDK:

@Documented
@Retention(RUNTIME)
@Target(ANNOTATION_TYPE)
public @interface Documented {
}

Thoạt nhìn có vẻ như:

@Documented
    ↓
@Documented
    ↓
@Documented
    ↓
...

Nhưng đây không phải recursion - nếu bạn hiểu theo hướng đệ quy.

@Documented chỉ là metadata, không phải một lời gọi hàm tạo ra chuỗi thực thi.

Có thể hiểu đơn giản:

Documented
└── được đánh dấu bằng @Documented

Hơn nữa:

@Target(ANNOTATION_TYPE)

cho phép @Documented được đặt lên annotation type. Mà Documented bản thân cũng là một annotation type, nên việc nó tự annotate chính nó là hoàn toàn hợp lệ.

Self-reference ≠ recursion. Recursion cần có quá trình thực thi lặp lại; @Documented chỉ là metadata.

Tóm lại

Annotation
   ↓
Meta-annotation
   ↓
@Documented
   ↓
"Đưa annotation này vào Javadoc"

@Documented không ảnh hưởng đến business logic hay cách chương trình chạy; nó chủ yếu ảnh hưởng đến việc annotation được thể hiện trong Javadoc.