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
-------------
Commit messages:
- refactor: move TagletWriter to the end of params
- refactor: make the throwsTagsOutput method private
- refactor: use var for Utils and CommentHelper
- fix: clarify the throwsTagsOutput doc comment
- fix: remove interference with subexceptions
- related: simplify skipping condition
- related: refactor CommentHelper.getExceptionName
- fix: improve the doc comment
- fix: update the "already documented" set later
- related: remove a nearby typo
Changes: https://git.openjdk.org/jdk19/pull/95/files
Webrev: https://webrevs.openjdk.org/?repo=jdk19&pr=95&range=00
Issue: https://bugs.openjdk.org/browse/JDK-8067757
Stats: 418 lines in 5 files changed: 361 ins; 13 del; 44 mod
Patch: https://git.openjdk.org/jdk19/pull/95.diff
Fetch: git fetch https://git.openjdk.org/jdk19 pull/95/head:pull/95
PR: https://git.openjdk.org/jdk19/pull/95
