On Mon, 27 May 2024 12:04:20 GMT, Nizar Benalla 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
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.(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
