On Thu, 30 Jun 2022 15:58:28 GMT, Pavel Rappo <[email protected]> wrote:
> Please review this PR for JDK 19.
>
> This PR fixes JDK-8067757. To understand what JDK-8067757 is about, you first
> need to understand how javadoc documents the fact that such and such
> exceptions are thrown by a constructor or method.
>
> If a constructor or method declaration indicates thrown exceptions, javadoc
> creates the "Throws:" section in that declaration documentation. Here's the
> algorithm which javadoc uses to fill in that section:
>
> 1. For each `@throws` tag that is directly present on the declaration, add an
> entry to the section.
> 2. If this is a method declaration, then for those exceptions from that
> declaration's `throws` clause for which there were no `@throws` tags found in
> step 1, try to inherit `@throws` tags from the overridden methods found as
> per Method Comments Algorithm[^1].
> 3. For each of the remaining exceptions from the `throws` clause (i.e. the
> exceptions for which documentation could neither be found in step 1, nor
> inherited in step 2), add an entry that mentions the exception but has no
> description.
>
> The problem that JDK-8067757 is concerned with is that if an exception is
> documented using multiple `@throws` tags, only one of these tags will be
> inherited in step 2.
>
> While fixing this issue I discovered an unpleasant interference with
> JDK-4947455[^2] and fixed it.
>
> Looking ahead, JDK-6509045[^3] is about a similar problem that happens in
> step 1 in the presence of `{@inheritDoc}`. I'm also planning to fix
> JDK-6509045 in JDK 19.
>
> [^1]:
> https://docs.oracle.com/en/java/javase/18/docs/specs/javadoc/doc-comment-spec.html#method-comments-algorithm
> [^2]: https://bugs.openjdk.org/browse/JDK-4947455
> [^3]: https://bugs.openjdk.org/browse/JDK-6509045
Nice.
This time, the individual change sets helped.
Thanks for working on the doc comments, in the places you did; they _do_ help.
-------------
Marked as reviewed by jjg (Reviewer).
PR: https://git.openjdk.org/jdk19/pull/95
