RFR: 8285488: Improve DocFinder [v5]

[Andrey Turbanov]

On Tue, 1 Nov 2022 15:32:09 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> 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 55 commits:
> 
>  - Merge branch 'master' into 8285488
>  - refactor: typos
>  - refactor: re-arrange imports conventionally
>  - refactor: clean up DocFinder
>  - refactor: improve comment and a catch block
>  - refactor: SuppressWarning("serial")
>  - 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
>  - ... and 45 more: https://git.openjdk.org/jdk/compare/37107fc1...385366d1

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ThrowsTaglet.java line 183:

> 181:             var ch = utils.getCommentHelper(f.holder());
> 182:             var messages = configuration.getMessages();
> 183:             if (f instanceof Failure.ExceptionTypeNotFound  e) {

Suggestion:

            if (f instanceof Failure.ExceptionTypeNotFound e) {

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

PR: https://git.openjdk.org/jdk/pull/10746