RFR: 8326951: Missing `@since` tags [v8]
Nizar Benalla
duke at openjdk.org
Mon May 13 20:24:58 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).
>
> for `MappedByteBuffer slice()` and `MappedByteBuffer slice(int index, int length)`, the return type changed from `ByteBuffer ` to `MappedByteBuffer`. And the checker tool differentiates between them because of that.
>
> 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 incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 15 additional commits since the last revision:
- Merge remote-tracking branch 'upstream/master' into add-missing-since-tags
- deal with methods with different return types - added some spaces for readability
- removed change
- Update full name
- update the copyright year to 2024
- Revert "update the copyright year to 2024"
This reverts commit 9ddd230dcf88bedade76a8e2804db6e120a200f8.
- update the copyright year to 2024
- added since tag
- Revert "fix rest of private/public since tags"
This reverts commit 2c04a9d8e773616b7b6239335d4e5eb955944ad1.
- Revert "removed unnecessary @ since tags"
This reverts commit 5da3f0d83d19393eeb3a9da68aac40dd999de660.
- ... and 5 more: https://git.openjdk.org/jdk/compare/893cd607...d3b8e64c
-------------
Changes:
- all: https://git.openjdk.org/jdk/pull/18055/files
- new: https://git.openjdk.org/jdk/pull/18055/files/670acaec..d3b8e64c
Webrevs:
- full: https://webrevs.openjdk.org/?repo=jdk&pr=18055&range=07
- incr: https://webrevs.openjdk.org/?repo=jdk&pr=18055&range=06-07
Stats: 592766 lines in 7064 files changed: 99933 ins; 147099 del; 345734 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