導入
Java開発において、アノテーションはコードにメタデータ（付加情報）を付与する強力な手段です。しかし、作成したカスタムアノテーションが「Javadocに表示されない」と悩んだことはありませんか？その課題を解決し、ドキュメントとしての完成度を高めるのが「@Documented」です。本記事では、アノテーションを正しくドキュメント化する方法を解説します。
基礎知識
アノテーションを定義する際、その振る舞いを制御するためのメタアノテーションがいくつか存在します。
@Retentionは「アノテーションをどの段階まで保持するか（ソースのみか、実行時までか）」を決め、@Targetは「クラスやメソッドなど、どこに付与できるか」を定義します。
そして@Documentedは、そのアノテーションがJavadocツールによって生成されるAPI仕様書に含まれるべきであることを示すマーカーです。これがないと、開発者が便利なアノテーションを使っていることに気づけない可能性があります。
実装/解決策
カスタムアノテーションを作成する際は、必ず@Documentedを付与することを習慣にしましょう。これにより、ライブラリの利用者に対して「このメソッドは特別な属性を持っている」という情報を確実に伝えることができます。
なお、リフレクションを用いて動的にアノテーションを読み取る場合は、RetentionPolicy.RUNTIMEを指定する必要があります。Proxyパターンと組み合わせる際にも、このメタデータは重要な役割を果たします。
サンプルプログラム
以下のコードをコピーして、プロジェクト内で動作確認してみてください。
import java.lang.annotation.;
// 1. RetentionをRUNTIMEに設定し、実行時に取得可能にする
// 2. Targetでメソッドにのみ適用可能にする
// 3. Documentedを付与してJavadocに表示させる
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Documented
public @interface MyCustomAnnotation {
String value() default “デフォルト値”;
}
// 使用例
public class SampleUsage {
/
- このメソッドはカスタムアノテーションを保持しています。
- Javadocを生成すると、@MyCustomAnnotationが表示されます。
/
@MyCustomAnnotation(value = “実行テスト”)
public void executeTask() {
System.out.println(“タスクを実行中…”);
}
}
応用・注意点
現場で陥りやすい罠として、「@Documentedを忘れることで、設計意図が伝わらない」というケースが挙げられます。特にフレームワークや共通ライブラリを開発する際、アノテーションを隠してしまうと、利用者がその機能の存在に気づけず、不要な設定を追加してしまうことがあります。
また、リフレクションでアノテーションを取得する際は、必ず対象のクラスやメソッドにアクセス可能な状態かを確認してください。Proxyオブジェクトを介してアノテーションを読み取る場合は、インターフェース側にアノテーションを定義する必要がある点にも注意しましょう。これらを意識することで、より保守性の高いコードベースを構築できます。
コメント