RFR: 8326836: Incorrect `@since` tags for ClassSignature methods [v4]

Nizar Benalla duke at openjdk.org
Fri Apr 19 09:27:22 UTC 2024


> # Issue
> - [JDK-8326836](https://bugs.openjdk.org/browse/JDK-8326836): changes were made to the method signatures but this modification isn't reflected in the @ since tags. The @ since tags need to be updated.
> 
> I changed the `@since` tags to better accurately show when the methods were introduced. This is similar to #18032 and #18373 
> 
> For context, I am writing tests to check for accurate use of `@since` tags in documentation comments in source code.
> We're following these rules for now:
> 
> ### Rule 1: Introduction of New Elements
> 
> - If an element is new in JDK N, with no equivalent in JDK N-1, it must include `@since N`.
>   - Exception: Member elements (fields, methods, nested classes) may omit `@since` if their version matches the value specified for the enclosing class or interface.
> 
> ### Rule 2: Existing Elements in Subsequent JDK Versions
> 
> - If an element exists in JDK N, with an equivalent in JDK N-1, it should not include `@since N`.
> 
> ### Rule 3: Handling Missing `@since` Tags in methods if there is no `@since`
> 
> - When inspecting methods, prioritize the `@since` annotation of the supertype's overridden method.
> - If unavailable or if the enclosing class's `@since` is newer, use the enclosing element's `@since`.
> 
>   I.e. if A extends B, and we add a method to B in JDK N, and add an override of the method to A in JDK M (M > N), we will use N as the effective `@since` for the method.

Nizar Benalla has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains five commits:

 - Merge branch 'master' into fix-classfile-related-since-tag
   
   # Conflicts:
   #	src/java.base/share/classes/java/lang/classfile/ClassFile.java
 - Update full name
 - update the copyright year to 2024
 - added @ since 23 to ClassFile.JAVA_23_VERSION, it now matches the @ since of the enclosing element
 - added @ since tag for of methods as their signature changed in jdk 23

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

Changes: https://git.openjdk.org/jdk/pull/18030/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18030&range=03
  Stats: 2 lines in 1 file changed: 2 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/18030.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18030/head:pull/18030

PR: https://git.openjdk.org/jdk/pull/18030


More information about the core-libs-dev mailing list