On Wed, 22 May 2024 13:58:21 GMT, Nizar Benalla <nbena...@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 incrementally with one additional
> commit since the last revision:
>
> Add a few more legacy methods, needed a few more after changes to the
> checker
Looks good to me, thanks for doing this!
test/jdk/tools/sincechecker/SinceChecker.java line 351:
> 349: }
> 350: String uniqueId = getElementName(te, element, types);
> 351: boolean isCommonMethod = uniqueId.endsWith("toString()") ||
Nit: `.toString()` instead of `toString()`?
-------------
Marked as reviewed by jlahoda (Reviewer).
PR Review: https://git.openjdk.org/jdk/pull/18934#pullrequestreview-2076973109
PR Review Comment: https://git.openjdk.org/jdk/pull/18934#discussion_r1613507278
