This is the second of the two PRs that fix inheritance for multiple `@throws`
tags for a particular exception.
The first PR (8067757, #95) fixed inheritance for multiple `@throws` tags for
an exception referred to by a `throws` clause. This PR fixes inheritance for
multiple `@throws` tags for an exception referred to by an `@throws` tag.
It is expected that if an overriding method has an `@throws` tag that has an
`{@inheritDoc}` in its description, then the documentation will inherit all
tags that describe that same exception in the overridden methods. For example,
support the setup looks like this:
* Overrider
```
@throws NullPointerException if this
@throws NullPointerException if that
```
* Overridee
```
@throws NullPointerException {@inheritDoc}
```
Then the overridee's documentation should look like this:
Throws:
NullPointerException - if this
NullPointerException - if that
While logical and expected, such behavior is different from other use cases of
`{@inheritDoc}`. In other use cases `{@inheritDoc}` expands locally: it
replaces itself with a list of tree nodes. Such a replacement doesn't affect
any tree node other than its parent.
`{@inheritDoc}` expands locally everywhere, such as in the main description,
`@param`, and `@return` tags, but it is not enough for `@throws`, which
sometimes needs to amend the **grandparent** node to replace a `@throws` node
with multiple `@throws` nodes. Amending this behavior globally just for
`@throws` would be impractical.
For now, it seems reasonable to fix this by overriding the `{@inheritDoc}`
processing just for `@throws`. This PR gives `ThrowsTaglet` an ability to peek
at `@throws` description to see if there are any `{@inheritDoc}` there.
There's one limitation though. Suppose `@throws` documentation is both amended
and inhertied from multiple `@throws` like this:
* Overridder
@throws NullPointerException if this
@throws NullPointerException if that
* Overridee
@throws NullPointerException "{@inheritDoc}"
It's not clear what to do in such a case. If only one of either amendment (a
`"` quote before and after) or multiple-inheritance is present, it's clear what
to do. But not when both are present. For now, such a situation is detected and
flagged as an error (a test is provided).
-------------
Commit messages:
- fix: raise an error not warning
- refactor: improve the `expand` method
- fix: add a combined test
- refactor: delete unused imports
- refactor: further split throwsTagsOutput
- refactor: improve extracted method (3)
- refactor: improve extracted method (2)
- refactor: improve extracted method
- fix: extract a method
- fix: use the element tags were inherited from
- ... and 1 more: https://git.openjdk.org/jdk19/compare/0526402a...702ff132
Changes: https://git.openjdk.org/jdk19/pull/116/files
Webrev: https://webrevs.openjdk.org/?repo=jdk19&pr=116&range=00
Issue: https://bugs.openjdk.org/browse/JDK-6509045
Stats: 271 lines in 2 files changed: 261 ins; 2 del; 8 mod
Patch: https://git.openjdk.org/jdk19/pull/116.diff
Fetch: git fetch https://git.openjdk.org/jdk19 pull/116/head:pull/116
PR: https://git.openjdk.org/jdk19/pull/116
