RFR: 8285488: Improve DocFinder [v2]

[Pavel Rappo]

> 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.

Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 40 commits:

 - Merge branch 'master' into 8285488
 - fix: process @throws {@inheritDoc} in ThrowsTaglet
 - Merge branch 'master' into 8285488
 - unrelated: use Text, not RawHtml for exceptions
   
   We are not expecting HTML in an exception name.
 - fix: remove auto-inheriting of subexceptions
   
   This effectively implements 8287796: Stop auto-inheriting documentation
   for subclasses of exceptions whose documentation is inherited.
   
   All tests pass. The only difference in the JDK API Documentation is
   the order of exceptions in some methods of RMIConnectionImpl_Stub:
   MBeanException and MBeanRegistrationException are ordered
   reversely. That difference is insignificant.
 - Merge branch 'master' into 8285488
 - Merge branch 'master' into 8285488
 - refactor: simplify compound ops on set
 - refactor: abstract out "Throws:" section building
   
   Why should ThrowsTaglet be constantly bothered with minor details such
   as if and when to add header?
 - refactor: support exceptions in DocFinder.search
   
   Provides a specialized version of Function, which can optionally throw
   a checked exception.
 - ... and 30 more: https://git.openjdk.org/jdk/compare/0233ba76...b0e21743

-------------

Changes: https://git.openjdk.org/jdk/pull/10746/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=10746&range=01
  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