<i18n dev> RFR: 8330954: Fix remaining `@since` tags in `java.base`

[Chen Liang]

On Mon, 29 Apr 2024 16:07:14 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Please review this PR that aims to add all the remaining needed `@since` tags in `java.base`, and group them into a single fix.
>> This is related to #18934 and my work around the `@since` checker feature.
>> Explicit `@since` tags are needed for some overriding methods for the purpose of the checker.
>> 
>> I will only give the example with the `CompletableFuture` class but here is the before where the methods only appeared in "Methods declared in interface N"
>> 
>> <img width="1510" alt="Screenshot 2024-05-06 at 00 06 57" src="https://github.com/openjdk/jdk/assets/96922791/1749a355-133b-4a38-bffe-51ac415b2aac">
>> 
>> 
>> 
>> and after where the method has it's own javadoc, the main description is added and the `@since` tags are added as intended.
>> 
>> I don't have an account on `https://cr.openjdk.org/` but I could host the generated docs somewhere if that is needed.
>> 
>> <img width="1511" alt="Screenshot 2024-05-06 at 00 07 16" src="https://github.com/openjdk/jdk/assets/96922791/89b92288-9b5e-48ed-8fa1-9342ea43e043">
>> 
>> <img width="1505" alt="Screenshot 2024-05-06 at 00 08 06" src="https://github.com/openjdk/jdk/assets/96922791/9aef08ff-5030-4189-a996-582a7eef849b">
>> 
>> <img width="1050" alt="Screenshot 2024-05-06 at 00 09 03" src="https://github.com/openjdk/jdk/assets/96922791/fdd75a26-0396-4c5e-8f59-a3717b7d7ec8">
>> 
>> 
>> TIA
>
> src/java.base/share/classes/java/io/FileInputStream.java line 345:
> 
>> 343:      * @throws    IllegalArgumentException {@inheritDoc}
>> 344:      * @throws    IOException {@inheritDoc}
>> 345:      * @throws    OutOfMemoryError {@inheritDoc}
> 
> Re: inheriting _unchecked_ exception documentation here and elsewhere in this PR
> 
> This PR's title suggests that the PR has nothing to do with exception documentation. If you feel that it should be addressed, please file a separate bug and move these changes there.
> 
> FWIW, I agree that `@throws ... {@inheritDoc}` for such exceptions are at least worth being considered. It's a common misconception that all exception documentation is inherited automatically.

This is because the tool from #18934 has no easy way to fetch the doc comment from a superclass/superinterface overridden method when this class only has a plain override. Javadoc handles this in complex logic in `VisibleMemberTable`; it's hard for other clients to try to emulate the behavior of doc finding, and the tool just incorrectly assumes such methods (what I have been talking about before) are reusing `@since` from the class docs.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18954#discussion_r1583449647