On Tue, 7 May 2024 17:37:57 GMT, Pavel Rappo <pra...@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
