RFR: 8331051: Add an `@since` checker test for `java.base` module [v6]
Nizar Benalla
nbenalla at openjdk.org
Sat May 18 21:26:27 UTC 2024
> 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 incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 13 additional commits since the last revision:
- 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`
- - Not checking elements enclosed within a record, I doubt a record class will change after being created
- Added a null check as `toString` can return an exception
- - Added some legacy modules that existed long before preview features (they were incubating)
- Not checking elements enclosed withing a record
- Only check if the file is readable using `Files.isReadable`
- Dropped the use of `Files.exists` and `Files.isDirectory`
- Use `--add-modules` option now to resolve certain modules
- mention packages in initial comment
- -Wrap lines at 80-100
-Changes `e.getMessages` to `e`
-`File.separator` to be platform indepedant
-Added a newline character at the end of files
-Rename `persistElement` to `processElement`
-Now throwing IllegalArgumentException instead of SkippedException
- trivial change - extra parentheses
- General improvements:
- added more detail to the initial comment
- ordered imports correctly
- renamed methods to be more consistent
- added predicate methods and 'isDocumented' 'isMember'
- added doc comments describing purpose of 'EffectiveSourceSinceHelper'
- Add more details to the initial comment
- ... and 3 more: https://git.openjdk.org/jdk/compare/aed682c5...e82dfbf0
-------------
Changes:
- all: https://git.openjdk.org/jdk/pull/18934/files
- new: https://git.openjdk.org/jdk/pull/18934/files/48c87814..e82dfbf0
Webrevs:
- full: https://webrevs.openjdk.org/?repo=jdk&pr=18934&range=05
- incr: https://webrevs.openjdk.org/?repo=jdk&pr=18934&range=04-05
Stats: 77304 lines in 2370 files changed: 38057 ins; 29029 del; 10218 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
More information about the core-libs-dev
mailing list