@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. |