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

[Nizar Benalla]

On Thu, 19 Sep 2024 16:38:54 GMT, Nizar Benalla <nbenalla 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.
>
> Nizar Benalla has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 28 commits:
> 
>  - Change "found" to "should be" in the error messages
>  - Merge remote-tracking branch 'upstream/master' into source-based-since-checker
>  - avoid using `continue`, fix mistake in last commit
>  - extend SinceChecker to now skip some packages
>  - Merge remote-tracking branch 'upstream/master' into source-based-since-checker
>  - Merge remote-tracking branch 'upstream/master' into source-based-since-checker
>  - Merge remote-tracking branch 'upstream/master' into source-based-since-checker
>  - Skip over files and packages that aren't found
>  - Move the tests to module/module_name directory for clearer naming
>  - (C)
>  - ... and 18 more: https://git.openjdk.org/jdk/compare/bc36ace7...d355222e

I performed a merge and a tiny change to the error message by the test.
The major changes since the last review are that I now skip packages if they are not found, and I added an exclude list to skip certain packages if we wish to do so.

Here is an example of the error output of the tool 

STDERR:
src/java.base/java/lang/classfile/TypeKind.java:73 field: java.lang.classfile.TypeKind:BOOLEAN: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:80 field: java.lang.classfile.TypeKind:BYTE: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:87 field: java.lang.classfile.TypeKind:CHAR: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:94 field: java.lang.classfile.TypeKind:SHORT: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:99 field: java.lang.classfile.TypeKind:INT: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:103 field: java.lang.classfile.TypeKind:LONG: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:107 field: java.lang.classfile.TypeKind:FLOAT: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:111 field: java.lang.classfile.TypeKind:DOUBLE: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:117 field: java.lang.classfile.TypeKind:REFERENCE: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:125 field: java.lang.classfile.TypeKind:VOID: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:143 method: java.lang.constant.ClassDesc java.lang.classfile.TypeKind.upperBound(): `@since` version: 22; should be: 24
java.lang.Exception: The `@since` checker found 64 problems
        at SinceChecker.checkModule(SinceChecker.java:265)
        at SinceChecker.main(SinceChecker.java:126)
        at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:103)
        at java.base/java.lang.reflect.Method.invoke(Method.java:573)
        at com.sun.javatest.regtest.agent.MainActionHelper$AgentVMRunnable.run(MainActionHelper.java:333)
        at java.base/java.lang.Thread.run(Thread.java:1576)

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

PR Comment: https://git.openjdk.org/jdk/pull/18934#issuecomment-2361549329