RFR: 8331051: Add an `@since` checker test for `java.base` module

[Hannes Wallnöfer]

On Wed, 24 Apr 2024 14:10:29 GMT, Nizar Benalla <duke at openjdk.org> wrote:

> This checker checks the values of the `@since` tag found in the documentation comment for an element against the release in which the element first appeared.
> 
> Real since value of an API element is computed as the oldest release in which the given API element was introduced. That is:
> - for modules, classes and interfaces, the release in which the element with the given qualified name was introduced
> - for constructors, the release in which the constructor with the given VM descriptor was introduced
> - for methods and fields, the release in which the given method or field with the given VM descriptor became a member of its enclosing class or interface, whether direct or inherited
> 
> Effective since value of an API element is computed as follows:
> - if the given element has a `@since` tag in its javadoc, it is used
> - in all other cases, return the effective since value of the enclosing element
> 
> The since checker verifies that for every API element, the real since value and the effective since value are the same, and reports an error if they are not.
> 
> Preview method are handled as per JEP 12, if `@PreviewFeature` is used consistently going forward then the checker doesn't need to be updated with every release. The checker has explicit knowledge of preview elements that came before `JDK 14` because they weren't marked in a machine understandable way and preview elements that came before `JDK 17` that didn't have `@PreviewFeature`.
> 
> Important note : We only check code written since `JDK 9` as the releases used to determine the expected value of `@since` tags are taken from the historical data built into `javac` which only goes back that far
> 
> The intial comment at the beginning of `SinceChecker.java` holds more information into the program.
> 
> I already have filed issues and fixed some wrong tags like in #18640, #18032, #18030, #18055, #18373, #18954, #18972.

test/jdk/tools/sincechecker/SinceChecker.java line 51:

> 49: 
> 50: /*
> 51: - This checker checks the values of the `@since` tag found in the documentation comment for an element against the release in which the element first appeared.

In addition to the long lines mentioned by Jon which make the comments hard to read, I find it strange that every sentence is formatted as a list item with a leading dash. I think it's ok when describing different parts/steps of the algorithm, but at least the first sentence in the comment should not be a list item IMO.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/18934#discussion_r1587671249