jdk icon indicating copy to clipboard operation
jdk copied to clipboard

Published 20 hours ago • verified publisher icon openjdk

8326951: Missing `@since` tags

Open nizarbenalla opened this issue 1 year ago • 6 comments

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.

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.

Progress

  • [ ] Change must be properly reviewed (1 review required, with at least 1 Reviewer)
  • [x] Change must not contain extraneous whitespace
  • [x] Commit message must refer to an issue

Issue

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/18055/head:pull/18055
$ git checkout pull/18055

Update a local copy of the PR:
$ git checkout pull/18055
$ git pull https://git.openjdk.org/jdk.git pull/18055/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 18055

View PR using the GUI difftool:
$ git pr show -t 18055

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/18055.diff

Webrev

Link to Webrev Comment

nizarbenalla avatar Feb 29 '24 09:02 nizarbenalla

Hi @nizarbenalla, welcome to this OpenJDK project and thanks for contributing!

We do not recognize you as Contributor and need to ensure you have signed the Oracle Contributor Agreement (OCA). If you have not signed the OCA, please follow the instructions. Please fill in your GitHub username in the "Username" field of the application. Once you have signed the OCA, please let us know by writing /signed in a comment in this pull request.

If you already are an OpenJDK Author, Committer or Reviewer, please click here to open a new issue so that we can record that fact. Please use "Add GitHub user nizarbenalla" as summary for the issue.

If you are contributing this work on behalf of your employer and your employer has signed the OCA, please let us know by writing /covered in a comment in this pull request.

bridgekeeper[bot] avatar Feb 29 '24 09:02 bridgekeeper[bot]

@nizarbenalla The following labels will be automatically applied to this pull request:

  • core-libs
  • nio

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing lists. If you would like to change these labels, use the /label pull request command.

openjdk[bot] avatar Feb 29 '24 09:02 openjdk[bot]

/covered

nizarbenalla avatar Mar 11 '24 14:03 nizarbenalla

You are already a known contributor!

bridgekeeper[bot] avatar Mar 11 '24 16:03 bridgekeeper[bot]

@nizarbenalla This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8326951: since-checker - missing @ since tags

Reviewed-by: jpai

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 294 new commits pushed to the master branch:

  • 31f70391e5f22ff5803d16b52c1e1248b6253d8c: 8316131: runtime/cds/appcds/TestParallelGCWithCDS.java fails with JNI error
  • 4a1cdd5ba947ffc88c1100966e68826eb35ed441: 8333486: Parallel: Remove unused methods in psParallelCompact
  • 664c993c41753843293388a6ff1481a94a5b4c22: 8331731: ubsan: relocInfo.cpp:155:30: runtime error: applying non-zero offset to null pointer
  • 8d3de45f4dfd60dc4e2f210cb0c085fcf6efb8e2: 8325168: JShell should support Markdown comments
  • 9ee741d1e55c2520b28a5e3ca0604073d81d0059: 8332015: since-checker - Add @ since tags to jdk.httpserver
  • 0f4154a9e9805534595feccc53a4a1abf20f99ae: 8331193: Return references when possible in GrowableArray
  • 64bbae75121ccf80c02a0960e2db62eb558052e6: 8333394: C2: assert(bol->is_Opaque4() || bol->is_OpaqueInitializedAssertionPredicate()) failed: Opaque node of non-null-check or of Initialized Assertion Predicate
  • c7495fb35d7736815d5777ab776ace013f9d50b5: 8333444: Parallel: Inline PSParallelCompact::mark_obj
  • 454660d361e39f362ff0e10a5c2389af910cca23: 8332900: RISC-V: refactor nativeInst_riscv.cpp and macroAssembler_riscv.cpp
  • 67d6f3ca9e8d1312c9e3a85dbe19903619f59064: 8332905: C2 SuperWord: bad AD file, with RotateRightV and first operand not a pack
  • ... and 284 more: https://git.openjdk.org/jdk/compare/5ded8da676d62158d0011086d7f80ff2c9096e13...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

As you do not have Committer status in this project an existing Committer must agree to sponsor your change. Possible candidates are the reviewers of this PR (@jaikiran) but any other Committer may sponsor as well.

➡️ To flag this PR as ready for integration with the above commit message, type /integrate in a new comment. (Afterwards, your sponsor types /sponsor in a new comment to perform the integration).

openjdk[bot] avatar Mar 13 '24 20:03 openjdk[bot]

Webrevs

mlbridge[bot] avatar Mar 15 '24 11:03 mlbridge[bot]

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
--------------------------------------------------

nizarbenalla avatar Jun 04 '24 00:06 nizarbenalla

Thanks for the thorough review!

/integrate

nizarbenalla avatar Jun 04 '24 13:06 nizarbenalla

/integrate

nizarbenalla avatar Jun 04 '24 14:06 nizarbenalla

/integrate

nizarbenalla avatar Jun 04 '24 16:06 nizarbenalla

@nizarbenalla Your change (at version e66fbf5a79ddc558aea02dede7527c2d914200bf) is now ready to be sponsored by a Committer.

openjdk[bot] avatar Jun 04 '24 16:06 openjdk[bot]

/sponsor

jaikiran avatar Jun 04 '24 16:06 jaikiran

@nizarbenalla Your change (at version e66fbf5a79ddc558aea02dede7527c2d914200bf) is now ready to be sponsored by a Committer.

openjdk[bot] avatar Jun 04 '24 16:06 openjdk[bot]

@nizarbenalla Your change (at version e66fbf5a79ddc558aea02dede7527c2d914200bf) is now ready to be sponsored by a Committer.

openjdk[bot] avatar Jun 04 '24 16:06 openjdk[bot]

Going to push as commit e0bab786402d70e9a74d1816c029c772ea01f697. Since your change was applied there have been 294 commits pushed to the master branch:

  • 31f70391e5f22ff5803d16b52c1e1248b6253d8c: 8316131: runtime/cds/appcds/TestParallelGCWithCDS.java fails with JNI error
  • 4a1cdd5ba947ffc88c1100966e68826eb35ed441: 8333486: Parallel: Remove unused methods in psParallelCompact
  • 664c993c41753843293388a6ff1481a94a5b4c22: 8331731: ubsan: relocInfo.cpp:155:30: runtime error: applying non-zero offset to null pointer
  • 8d3de45f4dfd60dc4e2f210cb0c085fcf6efb8e2: 8325168: JShell should support Markdown comments
  • 9ee741d1e55c2520b28a5e3ca0604073d81d0059: 8332015: since-checker - Add @ since tags to jdk.httpserver
  • 0f4154a9e9805534595feccc53a4a1abf20f99ae: 8331193: Return references when possible in GrowableArray
  • 64bbae75121ccf80c02a0960e2db62eb558052e6: 8333394: C2: assert(bol->is_Opaque4() || bol->is_OpaqueInitializedAssertionPredicate()) failed: Opaque node of non-null-check or of Initialized Assertion Predicate
  • c7495fb35d7736815d5777ab776ace013f9d50b5: 8333444: Parallel: Inline PSParallelCompact::mark_obj
  • 454660d361e39f362ff0e10a5c2389af910cca23: 8332900: RISC-V: refactor nativeInst_riscv.cpp and macroAssembler_riscv.cpp
  • 67d6f3ca9e8d1312c9e3a85dbe19903619f59064: 8332905: C2 SuperWord: bad AD file, with RotateRightV and first operand not a pack
  • ... and 284 more: https://git.openjdk.org/jdk/compare/5ded8da676d62158d0011086d7f80ff2c9096e13...master

Your commit was automatically rebased without conflicts.

openjdk[bot] avatar Jun 04 '24 16:06 openjdk[bot]

@jaikiran @nizarbenalla Pushed as commit e0bab786402d70e9a74d1816c029c772ea01f697.

:bulb: You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

openjdk[bot] avatar Jun 04 '24 16:06 openjdk[bot]