RFR: 8305457: Implement java.io.IO

[Pavel Rappo]

On Tue, 7 May 2024 16:24:52 GMT, Naoto Sato <naoto at openjdk.org> wrote:

>> Please review this PR which introduces the `java.io.IO` top-level class and three methods to `java.io.Console` for [Implicitly Declared Classes and Instance Main Methods (Third Preview)].
>> 
>> This PR has been obtained as `git merge --squash` of a now obsolete [draft PR].
>> 
>> [Implicitly Declared Classes and Instance Main Methods (Third Preview)]: https://bugs.openjdk.org/browse/JDK-8323335
>> [draft PR]: https://github.com/openjdk/jdk/pull/18921
>
> src/java.base/share/classes/java/io/ProxyingConsole.java line 107:
> 
>> 105:      * {@inheritDoc}
>> 106:      *
>> 107:      * @throws IOError {@inheritDoc}
> 
> Probably I am missing something, but I see `Console` declares this throws clause. Do we need this inheritDoc here?

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.

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

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