On Tue, 7 May 2024 16:24:52 GMT, Naoto Sato <na...@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
