Javadoc @since Tag Management
API tooling 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:
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().
- If we add a new method to C, say m2(), the tooling will report a missing
@since tag problem on m2() and suggest
that a new tag of @since 1.1 be placed on m2().
- If we add a new method to C, say m2() again and we change m1() - introduce a breaking API change - the tooling will report a
missing
@since tag problem on m2() and suggest that a new tag of @since 2.0 be place on m2(). Where 2.0.0
is the new proposed bundle version.
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:
-
@since A 1 added m2(): would be flagged as malformed because the version is missing the second segment
-
@since: would flagged as malformed since there is no version information
-
@since A: would be flagged since there is no version information
-
@since 1.0.0: would be flagged since the version has too many segments
-
@since A 1.0 added m2(): would not be flagged
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:
-
@since A 1.0 added method m2(): is considered valid
-
@since A 2.0 added method m2(): is invalid since the version of bundle A is 1.0.0
-
@since A 0.1 added method m2(): is invalid since the version of bundle A is 1.0.0
Setting up a baseline
API Baselines Preferences
API Errors and Warnings Preferences
