RFR: 8330954: Fix remaining `@since` tags in `java.base`
Pavel Rappo
prappo at openjdk.org
Sun May 5 23:33:05 UTC 2024
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
More information about the security-dev
mailing list