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
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java
line 507:
> 505: substituteType));
> 506: } else if (exception == null) {
> 507: excName = new
> RawHtml(throwsTag.getExceptionName().toString());
It's not your code or edit here, but I'll mention it anyway ...
We should be on the lookout for unnecessary use of `RawHtml`. It looks like
this is a candidate for a (later) cleanup to use just `Text`, not `RawHtml`.
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/CommentHelper.java
line 553:
> 551: return tt.getExceptionName();
> 552: }
> 553:
Yes, this does seem a bit superfluous
-------------
PR: https://git.openjdk.org/jdk19/pull/95
