API ツールは、API に追加された新規要素 (タイプ、メソッド、フィールドなど) 上で @since Javadoc タグを管理することを可能にします。新規 API 要素になるのは、API パッケージに追加された新規タイプ、API タイプに追加された新規メソッド、または API タイプに追加された新規フィールドです。
メソッドの追加は特殊なケースです。メソッドの追加とみなされるのは、タイプへのメソッドの追加、親クラスのメソッドのオーバーライド、親インターフェースのメソッドの実装、または既存メソッドのシグニチャーの変更です。
注: @since タグの情報は、実装やサブクラス化を介しては伝搬されません。
API に追加される各要素は、独自の @since タグとバージョン情報を持っているとみなされます。
API ツールでは、@since タグに関する以下の検証を行えます。
@since タグの管理に関する設定は、
「プラグイン開発」>「API エラーおよび警告」設定ページを使用して変更することができます。
検出されたすべての新規 API 要素は、@since タグを持っているかどうかが API ツールによって検査されます。
新規要素に @since タグがない場合、タグが必要であることを示すフラグが立てられ、そのタグのバージョンが提案されます。
新規タグについて提案されるバージョンは、API に急な変更が加えられた場合 (この場合はバンドルのバージョンも更新する必要があります) を除き、バンドルの現在のバージョンです。
バンドルのバージョンも更新しなければならない場合、欠落している @since タグについて提案されるバージョンは、提案されるバンドルのバージョンとなります。
1 つの例を考えます。バージョン 1.0.0 のバンドル A と、メソッド m1() を含むバージョン 1.1.0 の A で追加されたクラス C があるとします。
@since タグが欠落している問題について報告し、
新規タグ @since 1.1 を m2() に入れるよう提案します。@since タグが欠落している問題を報告し、新規タグ @since 2.0 を m2() に入れるよう提案します。
ここで、2.0.0 は、新しく提案されたバンドルのバージョンです。
新規要素では、@since タグの整合性を検査して、適切に配置されているかどうかを確認できます。
API ツールは、すべての @since タグが以下の一般的なフォーマットに従っているかどうかを検査します。
[@since] [pre-amble] [2 part version] [post-amble]
以下の @since タグの例について考えてみます。
@since A 1 added m2(): バージョンが 2 番目のセグメントで欠落しているため、誤った形式としてフラグが立てられます@since: バージョン情報がないため、誤った形式としてフラグが立てられます@since A: バージョン情報がないため、フラグが立てられます@since 1.0.0: バージョン部分のセグメントが多すぎるため、フラグが立てられます@since A 1.0 added m2(): フラグは立てられません
新規要素では、@since タグの妥当性も確認できます。
@since タグは、タグ中のバージョン情報がバンドルのバージョンと一致する場合に、有効であるとみなされます。
バージョンが 1.0.0 であるバンドル A 内の API クラスに新規メソッド m2() を追加したという例を考えてみます。
@since A 1.0 added method m2(): 有効であるとみなされます@since A 2.0 added method m2(): バンドル A のバージョンが 1.0.0 であるため、無効です@since A 0.1 added method m2(): バンドル A のバージョンが 1.0.0 であるため、無効です