> Please have a look at this work-in-progress PR. The reason this is a (normal)
> PR rather than a more suitable draft PR is to mainly trigger a discussion on
> the mailing list on whether the suggested approach to solve multiple
> intertwined issues of exception documentation inheritance is a correct one.
>
> In a nutshell, it turns out that the combination of `{@throws}` and
> `{@inheritDoc}` is quite complex. It's more complex than a combination of
> `{@inheritDoc}` with any other tag or `{@inheritDoc}` on its own. To account
> for that complexity, handling of `{@inheritDoc}` in `{@throws}` is lifted to
> `ThrowsTaglet`.
>
> The said complexity stems from two facts:
>
> 1. Processing of `{@inheritDoc}` is context free and is done by replacing
> `{@inheritDoc}` with the tags it expands to. That model does not account for
> `@throws` where `{@inheritDoc}` sometimes expands to multiple `@throws` tags,
> which correspond to _separate_ entries in the "Throws:" section of a method
> detail. Read: we change the exception section, not a description of one of
> its entries.
>
> 2. Corresponding exception types in the hierarchy (i.e. matching
> `{@inheritDoc}` with exception documentation it must inherit) is not always
> clear-cut. This becomes especially apparent when type variables are involved.
>
> History
> -------
>
> The work started as an attempt to fix JDK-8285488, hence the issue number for
> the PR. However, along its course the PR solved other issues, which will be
> soon added to the PR:
>
> * 8287796: Stop auto-inheriting documentation for subclasses of exceptions
> whose documentation is inherited
> * 8291869: Match exceptions using types of `javax.lang.model`, not strings
> * 8295277: Expand `{@inheritDoc}` in `@throws` fully
> * 8288045: Clean up ParamTaglet
> * 8288046: Clean up ThrowsTaglet
>
> As of today
> -----------
>
> * All tests (both existing and newly introduced) pass.
> * JDK API Documentation is the same, except for two files. In the first file,
> `docs/api/java.management.rmi/javax/management/remote/rmi/RMIConnectionImpl_Stub.html`,
> the order of exceptions has changed, which is insignificant. As for the
> second file, `docs/api/java.management/javax/management/MBeanServer.html`,
> the new warning is generated and erroneous input added to the corresponding
> page. The issue has to be addressed on the component side and is tracked by
> JDK-8295151.
Pavel Rappo has updated the pull request incrementally with four additional
commits since the last revision:
- Add a comment to InheritableTaglet.inherit
- Apply suggestion to rephrase "unsupported"
- Apply suggestion to rephrase error message
- Wrap long code lines
-------------
Changes:
- all: https://git.openjdk.org/jdk/pull/10746/files
- new: https://git.openjdk.org/jdk/pull/10746/files/ad5c0373..8e651d3b
Webrevs:
- full: https://webrevs.openjdk.org/?repo=jdk&pr=10746&range=07
- incr: https://webrevs.openjdk.org/?repo=jdk&pr=10746&range=06-07
Stats: 16 lines in 5 files changed: 6 ins; 0 del; 10 mod
Patch: https://git.openjdk.org/jdk/pull/10746.diff
Fetch: git fetch https://git.openjdk.org/jdk pull/10746/head:pull/10746
PR: https://git.openjdk.org/jdk/pull/10746
