[prev in list] [next in list] [prev in thread] [next in thread] 

List:       openjdk-core-libs-dev
Subject:    Re: RFR: 8331051: Add an `@since` checker test for `java.base` module
From:       Joe Darcy <darcy () openjdk ! org>
Date:       2024-04-29 16:51:05
Message-ID: QoVK_Zx-c2T-UXZpiMc6a2opdh74yUxQkYfTNG_UIeU=.23cefb45-96b7-444e-abeb-7a935c029506 () github ! com
[Download RAW message or body]

On Wed, 24 Apr 2024 14:10:29 GMT, Nizar Benalla <duke@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.

If not already planned, I recommend a much broader discussion/announcement of this \
test before it goes back. For example, a message to jdk-dev stating "The value of \
`@since` tags will be tested now by a tier $N test. This is how you run the test \
before a push. Here are rules for some tricky cases like introducing a covariant \
override." etc.

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

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


[prev in list] [next in list] [prev in thread] [next in thread]