RFR: 8326951: Missing `@since` tags [v6]

Nizar Benalla duke at openjdk.org
Tue Apr 16 15:59:27 UTC 2024


> I added `@since` tags for methods/constructors that do not match the `@since` of the enclosing class.
> 
> The `write` method already existed in `PrintStream` in earlier versions and instances of it could always call this method, since it extends `FilterOutputStream` [which has the method](https://github.com/openjdk/jdk6/blob/3e49aa876353eaa215cde71eb21acc9b7f9872a0/jdk/src/share/classes/java/io/FilterOutputStream.java#L96).
> 
> 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 incrementally with one additional commit since the last revision:

  removed change

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/18055/files
  - new: https://git.openjdk.org/jdk/pull/18055/files/97f4c946..390a21f9

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=18055&range=05
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=18055&range=04-05

  Stats: 1 line in 1 file changed: 0 ins; 1 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/18055.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18055/head:pull/18055

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


More information about the core-libs-dev mailing list