Summary

The behavior of the standard doclet is changed to use the @since value from the enclosing package as a default value if necessary.

Problem

A significant amount of older code lacks the @since tag, based on the belief that if a class was introduced alongside its package, the @since tag was unnecessary. Thus, the generated documentation for many classes does not include the @since tag. Users may wish to infer the @since value from the enclosing package to avoid the considerable manual effort of adding @since to every class.

Solution

Make the standard doclet more clever and always provide the @since information for every top-level declaration. If a class is missing the @since tag, look for the corresponding tag in the immediately enclosing package documentation file. If there is no since information in the package, we do not check the module version as classes and packages may not always be introduced in the same version as the module.

Specification

Extend the newly proposed @since spec with the following text

diff --git a/doc-comment-spec.md b/doc-comment-spec.md
--- a/doc-comment-spec.md
+++ b/doc-comment-spec.md
@@ -1212,7 +1212,9 @@
 tag in those cases where the value is different from that of the enclosing class
 or interface. If there are no `since` tags in the description for a member class
 or interface, the standard doclet will (recursively) look for any such tags in
-the enclosing class or interface.
+the enclosing class or interface. For top-level classes and interfaces, if there
+is no `since` tag on their declaration, the value may be inferred from that of
+the immediately enclosing package.

 _Note:_ One or more methods may be added implicitly to a class or interface as a
 result of adding additional supertypes in an `extends` or `implements` clause,