Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v10]
On Tue, 25 Jun 2024 08:29:42 GMT, Nizar Benalla 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 20 commits: > > - Move the tests to module/module_name directory for clearer naming > - (C) > - Merge remote-tracking branch 'upstream/master' into > source-based-since-checker > ># Conflicts: ># test/jdk/TEST.groups > - Improve checker report messages > - Merge branch 'master' into source-based-since-checker > - - removed unused parameter `i` >- make rest of methods private >- ".toString" instead of "toString" > >Signed-off-by: Nizar Benalla > - Add a few more legacy methods, needed a few more after changes to the > checker > - checking for null values directly rather than catching NPE > - Merge remote-tracking branch 'upstream/master' into > source-based-since-checker > - Now only skipping the common methods that every record class will have, > and will never need a new `@since` > - ... and 10 more: https://git.openjdk.org/jdk/compare/7baddc20...62aebb0b I have a couple of small changes after the first approval, mainly improving the error messages. And avoiding false reports in case a file doesn't exist in `src.zip` - PR Comment: https://git.openjdk.org/jdk/pull/18934#issuecomment-219691
Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v10]
> 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 20 commits: - Move the tests to module/module_name directory for clearer naming - (C) - Merge remote-tracking branch 'upstream/master' into source-based-since-checker # Conflicts: #test/jdk/TEST.groups - Improve checker report messages - Merge branch 'master' into source-based-since-checker - - removed unused parameter `i` - make rest of methods private - ".toString" instead of "toString" Signed-off-by: Nizar Benalla - Add a few more legacy methods, needed a few more after changes to the checker - checking for null values directly rather than catching NPE - Merge remote-tracking branch 'upstream/master' into source-based-since-checker - Now only skipping the common methods that every record class will have, and will never need a new `@since` - ... and 10 more: https://git.openjdk.org/jdk/compare/7baddc20...62aebb0b - Changes: https://git.openjdk.org/jdk/pull/18934/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18934&range=09 Stats: 959 lines in 3 files changed: 957 ins; 0 del; 2 mod Patch: https://git.openjdk.org/jdk/pull/18934.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/18934/head:pull/18934 PR: https://git.openjdk.org/jdk/pull/18934
