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

[Pavel Rappo]

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

This pull request has now been integrated.

Changeset: f640fc5a
Author:    Pavel Rappo <prappo at openjdk.org>
URL:       https://git.openjdk.org/jdk19/commit/f640fc5a1eb876a657d0de011dcd9b9a42b88eec
Stats:     418 lines in 5 files changed: 361 ins; 13 del; 44 mod

8067757: Incorrect HTML generation for copied javadoc with multiple @throws tags

Reviewed-by: jjg

-------------

PR: https://git.openjdk.org/jdk19/pull/95