RFR: 8326951: since-checker - missing @ since tags [v9]

[Jaikiran Pai]

On Mon, 13 May 2024 20:39:14 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> 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 incrementally with one additional commit since the last revision:
> 
>   empty commit and merge

These changes look good to me. Thank you Nizar for the work on the `@since` checker and these PRs in individual areas.

src/java.base/share/classes/java/util/zip/Deflater.java line 342:

> 340:      * @since 11
> 341:      */
> 342:     public void setDictionary(ByteBuffer dictionary) {

This method was introduced in Java 11 through https://bugs.openjdk.org/browse/JDK-6341887. It appears to be an oversight that a `@since 11` wasn't added to this method in that change, because other new methods introduced in that change did come with a `@since 11`. So this addition of `@since 11` now looks fine to me.

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

Marked as reviewed by jpai (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/18055#pullrequestreview-2096192264
PR Review Comment: https://git.openjdk.org/jdk/pull/18055#discussion_r1625879138