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
* 8285277: 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.
-------------
Commit messages:
- fix: process @throws {@inheritDoc} in ThrowsTaglet
- Merge branch 'master' into 8285488
- unrelated: use Text, not RawHtml for exceptions
- fix: remove auto-inheriting of subexceptions
- Merge branch 'master' into 8285488
- Merge branch 'master' into 8285488
- refactor: simplify compound ops on set
- refactor: abstract out "Throws:" section building
- refactor: support exceptions in DocFinder.search
- refactor: unused declaration
- ... and 29 more: https://git.openjdk.org/jdk/compare/172006c0...10cfc7f9
Changes: https://git.openjdk.org/jdk/pull/10746/files
Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=10746&range=00
Issue: https://bugs.openjdk.org/browse/JDK-8285488
Stats: 2020 lines in 25 files changed: 1407 ins; 322 del; 291 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
