RFR: 8285488: Improve DocFinder [v4]

[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
> * 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 with a new target base due to a merge or a rebase. The pull request now contains 49 commits:

 - refactor: improve error handling
 - refactor: clarify, reuse, simplify, clean up
 - refactor: pass Utils & BaseConfiguration to taglet
   
   This simplifies lots of methods. Later this could be done for other
   taglets too.
 - refactor: better code comments
 - refactor: add more relevant excerpts from JLS
 - fix: introduce more control to search
   
   This is done for the sake of `@throws`. Two convenience methods are
   added to assist migration from Optional with minimal change to
   DocFinder call sites.
   
   This solves 8295800: When searching documentation for an exception,
   don't jump over methods that don't mention that exception.
 - refactor: clean up ThrowsTaglet
 - Merge branch 'master' into HEAD
 - 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.
 - Merge branch 'master' into 8285488
 - ... and 39 more: https://git.openjdk.org/jdk/compare/628820f4...c2db1ae6

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

Changes: https://git.openjdk.org/jdk/pull/10746/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=10746&range=03
  Stats: 2089 lines in 27 files changed: 1468 ins; 230 del; 391 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