On Thu, 25 Apr 2024 16:43:50 GMT, Chen Liang <[email protected]> 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
