RFR: 8330954: Fix remaining `@since` tags in `java.base`

[Nizar Benalla]

On Thu, 25 Apr 2024 16:43:50 GMT, Chen Liang <liach at openjdk.org> wrote:

> I think your changes mostly group in these categories:
> 
> 1. New API methods provided in superclasses/superinterfaces, this class provides a more concrete implementation:
>    Examples being `CompletableFuture`, `FileInputStream`, `DelayQueue`, `FutureTask`
>    I don't think you should add since tags for these; without explicit javadoc, the methods inherit the superclass/superinterface docs, and appear in `Methods declared in class/interface Xxx` (supertype) section, which already have the correct since tags.
>    There's one scenario where such addition may be meaningful, however: that's if the supertype's since version is newer than this class/interfaces's since version, so we might need to specify here.
>    (On a side note, it would be great if we can mark the since version of an interface, notorious example being `ZipFile` retrofitted to implement `Closeable` in 1.7 and breaks compile target 1.6)
> 2. Remove unnecessary since tags for existing API methods with newer implementation
>    Examples being `Reference`, `RsaPrivateKey`. These make sense.
> 3. API methods with different return types
>    Examples being `ClassSignature`, `ClassDesc`. These make sense too, as older version may return different types. But problem here is should we count methods with only signature (but not descriptor) differences, like `ClassSignature::superinterfaceSignatures()`?

@liach 
- I am only looking at code added in JDK 9-current and do not plan on checking old code for now (in case there are questions on why certain methods weren't affected)
- I want generify-ing methods to be fine, so I am leaving `ClassSignature::superinterfaceSignatures()`. It will be changed eventually once the class goes out of Preview

> src/java.base/share/classes/java/lang/classfile/ClassSignature.java line 47:
> 
>> 45:      *
>> 46:      * @since 23
>> 47:      * */
> 
> Suggestion:
> 
>      */

good catch - will reply to your other questions later

> src/java.base/share/classes/java/lang/constant/MethodHandleDesc.java line 209:
> 
>> 207: 
>> 208:     /**
>> 209:      * @since 21
> 
> Suggestion:
> 
>      * {@inheritDoc}
>      *
>      * @since 21

Will need to look more into what elements require `{@inheritDoc}`

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

PR Comment: https://git.openjdk.org/jdk/pull/18954#issuecomment-2077922679
PR Review Comment: https://git.openjdk.org/jdk/pull/18954#discussion_r1579841341
PR Review Comment: https://git.openjdk.org/jdk/pull/18954#discussion_r1579880986