| Re: [wtp-dev] On the Correct Use of @since Javadoc Tags |
| Arthur Ryman/Toronto/IBM@IBMCA
Sent by: wtp-dev-bounces@xxxxxxxxxxx 11/17/2005 04:57 PM
|
|
| @since (reference
page) Specify the product version when the Java name was added to the API specification (if different from the implementation). For example, if a package, class, interface or member was added to the Java 2 Platform, Standard Edition, API Specification at version 1.2, use: /** * @since 1.2 */ The Javadoc standard doclet displays a "Since" subheading with the string argument as its text. This subheading appears in the generated text only in the place corresponding to where the @since tag appears in the source doc comments (The Javadoc tool does not proliferate it down the hierarchy). (The convention once was "@since JDK1.2" but because this is a specification of the Java Platform, not particular to the Sun JDK or SDK, we have dropped "JDK".) When a package is introduced, specify an @since tag in its package description and each of its classes. (Adding @since tags to each class is technically not needed, but is our convention, as enables greater visibility in the source code.) In the absence of overriding tags, the value of the @since tag applies to each of the package's classes and members. When a class (or interface) is introduced, specify one @since tag in its class description and no @since tags in the members. Add an @since tag only to members added in a later version than the class. This minimizes the number of @since tags. If a member changes from protected to public in a later release, the @since tag would not change, even though it is now usable by any caller, not just subclassers. |