> 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 one additional
commit since the last revision:
fix: test failed due to filesystem handling issues
Filed 8295543 to track that filesystem issue and fixed the test to make
sure the package cannot be confused with the type parameter, whose
name is not pertinent to the test anyway.
-------------
Changes:
- all: https://git.openjdk.org/jdk/pull/10746/files
- new: https://git.openjdk.org/jdk/pull/10746/files/b0e21743..001c4cbc
Webrevs:
- full: https://webrevs.openjdk.org/?repo=jdk&pr=10746&range=02
- incr: https://webrevs.openjdk.org/?repo=jdk&pr=10746&range=01-02
Stats: 9 lines in 1 file changed: 0 ins; 2 del; 7 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
