Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 

Eclipse Platform Plug-in Development Environment Guide
Previous Page Home Next Page

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

Related tasks
Setting up a baseline

Related reference
API Baselines Preferences
API Errors and Warnings Preferences


 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire