On Mon, 27 May 2024 12:04:20 GMT, Nizar Benalla <nbena...@openjdk.org> wrote:
>> This checker checks the values of the `@since` tag found in the
>> documentation comment for an element against the release in which the
>> element first appeared.
>>
>> Real since value of an API element is computed as the oldest release in
>> which the given API element was introduced. That is:
>> - for modules, classes and interfaces, the release in which the element with
>> the given qualified name was introduced
>> - for constructors, the release in which the constructor with the given VM
>> descriptor was introduced
>> - for methods and fields, the release in which the given method or field
>> with the given VM descriptor became a member of its enclosing class or
>> interface, whether direct or inherited
>>
>> Effective since value of an API element is computed as follows:
>> - if the given element has a `@since` tag in its javadoc, it is used
>> - in all other cases, return the effective since value of the enclosing
>> element
>>
>> The since checker verifies that for every API element, the real since value
>> and the effective since value are the same, and reports an error if they are
>> not.
>>
>> Preview method are handled as per JEP 12, if `@PreviewFeature` is used
>> consistently going forward then the checker doesn't need to be updated with
>> every release. The checker has explicit knowledge of preview elements that
>> came before `JDK 14` because they weren't marked in a machine understandable
>> way and preview elements that came before `JDK 17` that didn't have
>> `@PreviewFeature`.
>>
>> Important note : We only check code written since `JDK 9` as the releases
>> used to determine the expected value of `@since` tags are taken from the
>> historical data built into `javac` which only goes back that far
>>
>> The intial comment at the beginning of `SinceChecker.java` holds more
>> information into the program.
>>
>> I already have filed issues and fixed some wrong tags like in #18640,
>> #18032, #18030, #18055, #18373, #18954, #18972.
>
> Nizar Benalla has updated the pull request incrementally with one additional
> commit since the last revision:
>
> - removed unused parameter `i`
> - make rest of methods private
> - ".toString" instead of "toString"
>
> Signed-off-by: Nizar Benalla <nizar.bena...@oracle.com>
The checker's report has been improved, the result after running it on
`java.base` is the following
SinceChecker java.base
STDERR:
src/java.base/java/io/PrintStream.java:685 method: void
java.io.PrintStream.write(byte[]): `@since` version is 14 but the element
exists before JDK 10
src/java.base/java/io/FileInputStream.java:374 method: byte[]
java.io.FileInputStream.readNBytes(int): `@since` version: 9; found: 11
src/java.base/java/lang/classfile/ClassSignature.java:45 method:
java.lang.classfile.Signature.ClassTypeSig
java.lang.classfile.ClassSignature.superclassSignature(): `@since` version: 22;
found: 23
src/java.base/java/lang/classfile/ClassReader.java:131 method:
java.lang.classfile.constantpool.PoolEntry
java.lang.classfile.ClassReader.readEntryOrNull(int,java.lang.Class): `@since`
version: 24; found: 23
src/java.base/java/lang/classfile/constantpool/ConstantPool.java:74 method:
java.lang.classfile.constantpool.PoolEntry
java.lang.classfile.constantpool.ConstantPool.entryByIndex(int,java.lang.Class):
`@since` version: 24; found: 23
src/java.base/java/lang/constant/ClassDesc.java:378 method: java.lang.Class
java.lang.constant.ClassDesc.resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup):
`@since` version: 12; found: 21
src/java.base/java/lang/constant/MethodTypeDesc.java:226 method:
java.lang.invoke.MethodType
java.lang.constant.MethodTypeDesc.resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup):
`@since` version: 12; found: 21
src/java.base/java/lang/constant/MethodHandleDesc.java:210 method:
java.lang.invoke.MethodHandle
java.lang.constant.MethodHandleDesc.resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup):
`@since` version: 12; found: 21
src/java.base/java/lang/foreign/MemorySegment.java:622 method: long
java.lang.foreign.MemorySegment.maxByteAlignment(): `@since` version: 22;
found: 23
src/java.base/java/lang/invoke/MethodHandles.java:7923 method:
java.lang.invoke.MethodHandle
java.lang.invoke.MethodHandles.tableSwitch(java.lang.invoke.MethodHandle,java.lang.invoke.MethodHandle[]):
`@since` version: 9; found: 17
src/java.base/java/lang/ref/Reference.java:527 method: java.lang.Object
java.lang.ref.Reference.clone(): `@since` version is 11 but the element exists
before JDK 10
src/java.base/java/lang/reflect/MalformedParameterizedTypeException.java:54
method: void
java.lang.reflect.MalformedParameterizedTypeException.<init>(java.lang.String):
`@since` version: 9; found: 10
src/java.base/java/nio/MappedByteBuffer.java:401 method:
java.nio.MappedByteBuffer java.nio.MappedByteBuffer.slice(): `@since` version:
9; found: 17
src/java.base/java/nio/MappedByteBuffer.java:414 method:
java.nio.MappedByteBuffer java.nio.MappedByteBuffer.slice(int,int): `@since`
version: 9; found: 17
src/java.base/java/nio/MappedByteBuffer.java:420 method:
java.nio.MappedByteBuffer java.nio.MappedByteBuffer.duplicate(): `@since`
version: 9; found: 17
src/java.base/java/nio/MappedByteBuffer.java:427 method:
java.nio.MappedByteBuffer java.nio.MappedByteBuffer.compact(): `@since`
version: 9; found: 17
src/java.base/java/text/ChoiceFormat.java:589 method: boolean
java.text.ChoiceFormat.isStrict(): `@since` version: 9; found: 23
src/java.base/java/text/ChoiceFormat.java:595 method: void
java.text.ChoiceFormat.setStrict(boolean): `@since` version: 9; found: 23
src/java.base/java/util/Properties.java:189 method: void
java.util.Properties.<init>(int): `@since` version: 9; found: 10
src/java.base/java/util/concurrent/FutureTask.java:208 method: java.lang.Object
java.util.concurrent.FutureTask.resultNow(): `@since` version: 9; found: 19
src/java.base/java/util/concurrent/FutureTask.java:224 method:
java.lang.Throwable java.util.concurrent.FutureTask.exceptionNow(): `@since`
version: 9; found: 19
src/java.base/java/util/concurrent/FutureTask.java:239 method:
java.util.concurrent.Future.State java.util.concurrent.FutureTask.state():
`@since` version: 9; found: 19
src/java.base/java/util/concurrent/ThreadLocalRandom.java:504 method: float
java.util.concurrent.ThreadLocalRandom.nextFloat(float): `@since` version: 9;
found: 17
src/java.base/java/util/concurrent/ThreadLocalRandom.java:514 method: float
java.util.concurrent.ThreadLocalRandom.nextFloat(float,float): `@since`
version: 9; found: 17
src/java.base/java/util/concurrent/ForkJoinTask.java:890 method:
java.util.concurrent.Future.State java.util.concurrent.ForkJoinTask.state():
`@since` version: 9; found: 19
src/java.base/java/util/concurrent/ForkJoinTask.java:899 method:
java.lang.Object java.util.concurrent.ForkJoinTask.resultNow(): `@since`
version: 9; found: 19
src/java.base/java/util/concurrent/ForkJoinTask.java:913 method:
java.lang.Throwable java.util.concurrent.ForkJoinTask.exceptionNow(): `@since`
version: 9; found: 19
src/java.base/java/util/concurrent/DelayQueue.java:331 method:
java.util.concurrent.Delayed java.util.concurrent.DelayQueue.remove(): `@since`
version: 9; found: 21
src/java.base/java/util/concurrent/CompletableFuture.java:2137 method:
java.lang.Object java.util.concurrent.CompletableFuture.resultNow(): `@since`
version: 9; found: 19
src/java.base/java/util/concurrent/CompletableFuture.java:2152 method:
java.lang.Throwable java.util.concurrent.CompletableFuture.exceptionNow():
`@since` version: 9; found: 19
src/java.base/java/util/concurrent/CompletableFuture.java:2399 method:
java.util.concurrent.CompletableFuture
java.util.concurrent.CompletableFuture.exceptionallyAsync(java.util.function.Function):
`@since` version: 9; found: 12
src/java.base/java/util/concurrent/CompletableFuture.java:2404 method:
java.util.concurrent.CompletableFuture
java.util.concurrent.CompletableFuture.exceptionallyAsync(java.util.function.Function,java.util.concurrent.Executor):
`@since` version: 9; found: 12
src/java.base/java/util/concurrent/CompletableFuture.java:2409 method:
java.util.concurrent.CompletableFuture
java.util.concurrent.CompletableFuture.exceptionallyCompose(java.util.function.Function):
`@since` version: 9; found: 12
src/java.base/java/util/concurrent/CompletableFuture.java:2414 method:
java.util.concurrent.CompletableFuture
java.util.concurrent.CompletableFuture.exceptionallyComposeAsync(java.util.function.Function):
`@since` version: 9; found: 12
src/java.base/java/util/concurrent/CompletableFuture.java:2419 method:
java.util.concurrent.CompletableFuture
java.util.concurrent.CompletableFuture.exceptionallyComposeAsync(java.util.function.Function,java.util.concurrent.Executor):
`@since` version: 9; found: 12
src/java.base/java/util/concurrent/CompletableFuture.java:2544 method:
java.util.concurrent.Future.State
java.util.concurrent.CompletableFuture.state(): `@since` version: 9; found: 19
src/java.base/java/util/zip/Deflater.java:340 method: void
java.util.zip.Deflater.setDictionary(java.nio.ByteBuffer): `@since` version: 9;
found: 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
--------------------------------------------------
Test results: failed: 1
-------------
PR Comment: https://git.openjdk.org/jdk/pull/18934#issuecomment-2148385307
