Javadoc @since Tag Management

API Tools provides support for management of @since Javadoc tags on new elements that have been added to API (types, methods, fields, etc). New API elements could be a new type added to an API package, a new type added to an API type, a new method added to an API type or a new field added to an API type. Method addition is a special case, where a method addition could be adding a method to a type, overriding a parent class method, implementing a parent interface method or changing an existing methods' signature.

Note: @since tag information is not propagated via implementation or sub-classing. Each element that is added to API is expected to have its' own @since tag and version information.

The tooling provides the following validation for @since tags:

The preferences for @since tag management can be changed on the Opens the Console preference page Plug-in Development > API Errors/Warnings preference page.

Missing @since tags

Every new API element detected will be checked by the tooling to ensure it has an @since tag. If the new element does not have an @since tag, it will be flagged as needing one, and a version for the tag will be proposed. The proposed version for the new tag will be the current version of the bundle - except in the case of a breaking API change where the bundle version also needs to be updated. If the bundle version also needs to be updated, the proposed version for the missing @since tag will be that of the proposed bundle version.

Consider the following example: we have a bundle A with version 1.0.0 and we have a class C that was added in version 1.1.0 of A which contains method m1().

Malformed @since tags

New elements can have their @since tags checked for consistency to ensure they are properly formulated. API tools checks that all @since tags follow the general format of:

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

Consider the following @since tag examples:

Invalid @since tag versions

New elements can also have their @since tags checked for validity. An @since tag is considered to be valid if the version information in the tag matches the version of the bundle.

Consider the following example where we have added a new method m2() to an API class in bundle A whose version is 1.0.0:

Related tasks
Setting up a baseline

Related reference
API Baselines Preferences
API Errors and Warnings Preferences