Parent issue: #19807
Coverage table
Chapter link
Content
Image
Text
@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:
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 Oracle 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.
Guidelines
We can validate that @since tag has a description. Proposal:
| Documentation Comments Rule |
Checkstyle Checks Used |
Sample files |
@since |
✅NonEmptyAtclauseDescription (needs update) |
|
Parent issue: #19807
Coverage table
Chapter link
Content
Image
Text
@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:
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
@sincetag 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 Oracle JDK or SDK, we have dropped "JDK".)When a package is introduced, specify an
@sincetag in its package description and each of its classes. (Adding@sincetags 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@sincetag applies to each of the package's classes and members.When a class (or interface) is introduced, specify one
@sincetag in its class description and no@sincetags in the members. Add an@sincetag only to members added in a later version than the class. This minimizes the number of@sincetags.If a member changes from protected to public in a later release, the
@sincetag would not change, even though it is now usable by any caller, not just subclassers.Guidelines
We can validate that
@sincetag has a description. Proposal:@since