RFR: 8331051: Add an `@since` checker test for `java.base` module
Nizar Benalla
duke at openjdk.org
Wed May 1 21:19:55 UTC 2024
On Wed, 1 May 2024 20:53:08 GMT, Jonathan Gibbons <jjg 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 53:
>
>> 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.
>> 52: - The source code containing the documentation comments is read from `src.zip` in the release of JDK used to run the test.
>> 53: - The releases used to determine the expected value of `@since` tags are taken from the historical data built into `javac`.
>
> (Minor, suggest wrapping lines somewhere between 80-100 characters long)
My idea was that, even when comparing files in a merge conflit, there wouldn't be problems here.
But I will fix, some lines in the code are a bit long as well
> test/jdk/tools/sincechecker/SinceChecker.java line 72:
>
>> 70:
>> 71: Real since value of an API element is computed as the oldest release in which the given API element was introduced. That is:
>> 72: - for modules, classes and interfaces, the release in which the element with the given qualified name was introduced
>
> What about packages? packages should be in this list as well.
Small oversight, will fix
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/18934#discussion_r1586840002
PR Review Comment: https://git.openjdk.org/jdk/pull/18934#discussion_r1586838616
More information about the core-libs-dev
mailing list