RFR: 8305457: Implement java.io.IO [v3]

[Joe Darcy]

On Tue, 7 May 2024 17:37:57 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> Yes, we do. There's a common misconception that `{@inheritDoc}` inherits the complete doc comment. In reality, `{@inheritDoc}` inherits only the main description, which does not include any `@throws` tags.
> 
> A `@throws` tag is either inherited explicitly, such as in L107, or implicitly. Implicit inheritance occurs when an exception is listed in the `throws` clause.
> 
> Since it's uncommon for unchecked exceptions (errors included) to be listed in the `throws` clause, unless inherited explicitly, their documentation will be missing from the overriding method documentation. Assuming, of course, that your intention is to have them there.

While it may be surprising that `{@inheritDoc}` doesn't inherit the complete doc, it is a feature rather than a bug since an overridden method is allowed to throw fewer exceptions than the method it overrides.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/19112#discussion_r1592985138