[jdk19] RFR: 8067757: Incorrect HTML generation for copied javadoc with multiple @throws tags

[Jonathan Gibbons]

On Thu, 30 Jun 2022 15:58:28 GMT, Pavel Rappo <prappo at openjdk.org> 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