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

[Nizar Benalla]

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

Here is a snippet from the report of the checker with the relevant bits for this PR

STDERR:
method: void java.io.PrintStream.write(byte[]): `@since` version is 14 but the element exists before JDK 10
method: java.lang.invoke.MethodHandle java.lang.invoke.MethodHandles.tableSwitch(java.lang.invoke.MethodHandle,java.lang.invoke.MethodHandle[]): `@since` version is 9 instead of 17
method: void java.lang.reflect.MalformedParameterizedTypeException.<init>(java.lang.String): `@since` version is 9 instead of 10
method: java.nio.MappedByteBuffer java.nio.MappedByteBuffer.slice(): `@since` version is 9 instead of 17
method: java.nio.MappedByteBuffer java.nio.MappedByteBuffer.slice(int,int): `@since` version is 9 instead of 17
method: java.nio.MappedByteBuffer java.nio.MappedByteBuffer.duplicate(): `@since` version is 9 instead of 17
method: java.nio.MappedByteBuffer java.nio.MappedByteBuffer.compact(): `@since` version is 9 instead of 17
method: void java.util.Properties.<init>(int): `@since` version is 9 instead of 10
method: float java.util.concurrent.ThreadLocalRandom.nextFloat(float): `@since` version is 9 instead of 17
method: float java.util.concurrent.ThreadLocalRandom.nextFloat(float,float): `@since` version is 9 instead of 17
method: void java.util.zip.Deflater.setDictionary(java.nio.ByteBuffer): `@since` version is 9 instead of 11




Here is the full report

STDERR:
method: void java.io.PrintStream.write(byte[]): `@since` version is 14 but the element exists before JDK 10
method: byte[] java.io.FileInputStream.readNBytes(int): `@since` version is 9 instead of 11
method: java.lang.classfile.Signature.ClassTypeSig java.lang.classfile.ClassSignature.superclassSignature(): `@since` version is 22 instead of 23
method: java.lang.classfile.constantpool.PoolEntry java.lang.classfile.ClassReader.readEntryOrNull(int,java.lang.Class): `@since` version is 24 instead of 23
method: java.lang.classfile.constantpool.PoolEntry java.lang.classfile.constantpool.ConstantPool.entryByIndex(int,java.lang.Class): `@since` version is 24 instead of 23
method: java.lang.Class java.lang.constant.ClassDesc.resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup): `@since` version is 12 instead of 21
method: java.lang.invoke.MethodType java.lang.constant.MethodTypeDesc.resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup): `@since` version is 12 instead of 21
method: java.lang.invoke.MethodHandle java.lang.constant.MethodHandleDesc.resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup): `@since` version is 12 instead of 21
method: long java.lang.foreign.MemorySegment.maxByteAlignment(): `@since` version is 22 instead of 23
method: java.lang.invoke.MethodHandle java.lang.invoke.MethodHandles.tableSwitch(java.lang.invoke.MethodHandle,java.lang.invoke.MethodHandle[]): `@since` version is 9 instead of 17
method: java.lang.Object java.lang.ref.Reference.clone(): `@since` version is 11 but the element exists before JDK 10
method: void java.lang.reflect.MalformedParameterizedTypeException.<init>(java.lang.String): `@since` version is 9 instead of 10
method: java.nio.MappedByteBuffer java.nio.MappedByteBuffer.slice(): `@since` version is 9 instead of 17
method: java.nio.MappedByteBuffer java.nio.MappedByteBuffer.slice(int,int): `@since` version is 9 instead of 17
method: java.nio.MappedByteBuffer java.nio.MappedByteBuffer.duplicate(): `@since` version is 9 instead of 17
method: java.nio.MappedByteBuffer java.nio.MappedByteBuffer.compact(): `@since` version is 9 instead of 17
method: boolean java.text.ChoiceFormat.isStrict(): `@since` version is 9 instead of 23
method: void java.text.ChoiceFormat.setStrict(boolean): `@since` version is 9 instead of 23
method: void java.util.Properties.<init>(int): `@since` version is 9 instead of 10
method: java.lang.Object java.util.concurrent.FutureTask.resultNow(): `@since` version is 9 instead of 19
method: java.lang.Throwable java.util.concurrent.FutureTask.exceptionNow(): `@since` version is 9 instead of 19
method: java.util.concurrent.Future.State java.util.concurrent.FutureTask.state(): `@since` version is 9 instead of 19
method: float java.util.concurrent.ThreadLocalRandom.nextFloat(float): `@since` version is 9 instead of 17
method: float java.util.concurrent.ThreadLocalRandom.nextFloat(float,float): `@since` version is 9 instead of 17
method: java.util.concurrent.Future.State java.util.concurrent.ForkJoinTask.state(): `@since` version is 9 instead of 19
method: java.lang.Object java.util.concurrent.ForkJoinTask.resultNow(): `@since` version is 9 instead of 19
method: java.lang.Throwable java.util.concurrent.ForkJoinTask.exceptionNow(): `@since` version is 9 instead of 19
method: java.util.concurrent.Delayed java.util.concurrent.DelayQueue.remove(): `@since` version is 9 instead of 21
method: java.lang.Object java.util.concurrent.CompletableFuture.resultNow(): `@since` version is 9 instead of 19
method: java.lang.Throwable java.util.concurrent.CompletableFuture.exceptionNow(): `@since` version is 9 instead of 19
method: java.util.concurrent.CompletableFuture java.util.concurrent.CompletableFuture.exceptionallyAsync(java.util.function.Function): `@since` version is 9 instead of 12
method: java.util.concurrent.CompletableFuture java.util.concurrent.CompletableFuture.exceptionallyAsync(java.util.function.Function,java.util.concurrent.Executor): `@since` version is 9 instead of 12
method: java.util.concurrent.CompletableFuture java.util.concurrent.CompletableFuture.exceptionallyCompose(java.util.function.Function): `@since` version is 9 instead of 12
method: java.util.concurrent.CompletableFuture java.util.concurrent.CompletableFuture.exceptionallyComposeAsync(java.util.function.Function): `@since` version is 9 instead of 12
method: java.util.concurrent.CompletableFuture java.util.concurrent.CompletableFuture.exceptionallyComposeAsync(java.util.function.Function,java.util.concurrent.Executor): `@since` version is 9 instead of 12
method: java.util.concurrent.Future.State java.util.concurrent.CompletableFuture.state(): `@since` version is 9 instead of 19
method: void java.util.zip.Deflater.setDictionary(java.nio.ByteBuffer): `@since` version is 9 instead of 11
java.lang.Exception: The `@since` checker found 37 problems
        at SinceChecker.checkModule(SinceChecker.java:262)
        at SinceChecker.main(SinceChecker.java:123)
        at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:103)
        at java.base/java.lang.reflect.Method.invoke(Method.java:580)
        at com.sun.javatest.regtest.agent.MainActionHelper$AgentVMRunnable.run(MainActionHelper.java:333)
        at java.base/java.lang.Thread.run(Thread.java:1575)

JavaTest Message: Test threw exception: java.lang.Exception
JavaTest Message: shutting down test


TEST RESULT: Failed. Execution failed: `main' threw exception: java.lang.Exception: The `@since` checker found 37 problems
--------------------------------------------------

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

PR Comment: https://git.openjdk.org/jdk/pull/18055#issuecomment-2146354662