On Wed, 24 Apr 2024 14:10:29 GMT, Nizar Benalla <[email protected]> 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 106:
> 104: public static void main(String[] args) throws Exception {
> 105: if (args.length == 0) {
> 106: throw new SkippedException("Test module not specified");
I don't think `SkippedException` is the right exception to throw here, since
invoking the method with a missing argument is probably a configuration error
that shouldn't be ignored. Maybe `IllegalArgumentException` or just
`RuntimeException`?
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/18934#discussion_r1587701335
