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

[Jonathan Gibbons]

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

For discussion:

I see that in GitHub Actions, the test passes on all platforms. (That's good!). But it's not clear to me that it _needs_ to run on all platforms. Generally, the API should be the same on all platforms, right (After all, we only generate one set of API documentation.) 

So, the question becomes, can a test determine if it is being run in a multi-platform context?  We presumably don't want to stop the test running whenever a user runs it locally on their platform of choice, but equally, if the test is being run on many platforms, that's an unnecessary use/waste of resources.  But, I guess we run a lot of tests that are essentially platform-independent on all platforms, although I guess there're are also testing the product running on top of the JVM, whereas here. we're primarily just checking the source.

Anyway, this is really just an abstract academic discussion, not a blocker in any way for the PR.

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

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