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

[Pavel Rappo]

On Thu, 25 Apr 2024 14:29:27 GMT, Nizar Benalla <duke 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.

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

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