Javadoc @since タグの管理

API ツールは、API に追加された新規要素 (タイプ、メソッド、フィールドなど) 上で @since Javadoc タグを管理することを可能にします。新規 API 要素になるのは、API パッケージに追加された新規タイプ、API タイプに追加された新規メソッド、または API タイプに追加された新規フィールドです。 メソッドの追加は特殊なケースです。メソッドの追加とみなされるのは、タイプへのメソッドの追加、親クラスのメソッドのオーバーライド、親インターフェースのメソッドの実装、または既存メソッドのシグニチャーの変更です。

注: @since タグの情報は、実装やサブクラス化を介しては伝搬されません。 API に追加される各要素は、独自の @since タグとバージョン情報を持っているとみなされます。

API ツールでは、@since タグに関する以下の検証を行えます。

@since タグの管理に関する設定は、 「コンソール」設定ページを開く「プラグイン開発」>「API エラーおよび警告」設定ページを使用して変更することができます。

@since タグの欠落

検出されたすべての新規 API 要素は、@since タグを持っているかどうかが API ツールによって検査されます。 新規要素に @since タグがない場合、タグが必要であることを示すフラグが立てられ、そのタグのバージョンが提案されます。 新規タグについて提案されるバージョンは、API に急な変更が加えられた場合 (この場合はバンドルのバージョンも更新する必要があります) を除き、バンドルの現在のバージョンです。 バンドルのバージョンも更新しなければならない場合、欠落している @since タグについて提案されるバージョンは、提案されるバンドルのバージョンとなります。

1 つの例を考えます。バージョン 1.0.0 のバンドル A と、メソッド m1() を含むバージョン 1.1.0 の A で追加されたクラス C があるとします。

誤った形式の @since タグ

新規要素では、@since タグの整合性を検査して、適切に配置されているかどうかを確認できます。 API ツールは、すべての @since タグが以下の一般的なフォーマットに従っているかどうかを検査します。

[@since] [pre-amble] [2 part version] [post-amble]

以下の @since タグの例について考えてみます。

無効な @since タグ・バージョン

新規要素では、@since タグの妥当性も確認できます。 @since タグは、タグ中のバージョン情報がバンドルのバージョンと一致する場合に、有効であるとみなされます。

バージョンが 1.0.0 であるバンドル A 内の API クラスに新規メソッド m2() を追加したという例を考えてみます。

関連タスク
ベースラインのセットアップ

関連参照
API ベースラインの設定
API エラーおよび警告に関する設定