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

[Nizar Benalla]

On Tue, 4 Jun 2024 20:44:30 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 incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 17 additional commits since the last revision:
> 
>  - Improve checker report messages
>  - Merge branch 'master' into source-based-since-checker
>  - - removed unused parameter `i`
>    - make rest of methods private
>    - ".toString" instead of "toString"
>    
>    Signed-off-by: Nizar Benalla <nizar.benalla at oracle.com>
>  - Add a few more legacy methods, needed a few more after changes to the checker
>  - checking for null values directly rather than catching NPE
>  - Merge remote-tracking branch 'upstream/master' into source-based-since-checker
>  - Now only skipping the common methods that every record class will have, and will never need a new `@since`
>  - - Not checking elements enclosed within a record, I doubt a record class will change after being created
>    - Added a null check as `toString` can return an exception
>  - - Added some legacy modules that existed long before preview features (they were incubating)
>    - Not checking elements enclosed withing a record
>    - Only check if the file is readable using `Files.isReadable`
>    - Dropped the use of `Files.exists` and `Files.isDirectory`
>    - Use `--add-modules` option now to resolve certain modules
>  - mention packages in initial comment
>  - ... and 7 more: https://git.openjdk.org/jdk/compare/026b5fc2...5be962b7

While this might seem like a lot, if a developer runs it before pushing, they should only encounter a few reports at most.

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

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