# 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:

- Missing `@since` tags
- Malformed `@since` tags
- Invalid `@since` tag versions

The preferences for `@since` tag management can be changed on the 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().

- 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

### Related tasks

Setting up a baseline

### Related references

API Baselines Preferences
API Errors and Warnings Preferences