RFR: 8285488: Improve DocFinder [v4]

[Pavel Rappo]

On Fri, 28 Oct 2022 18:58:38 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> 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
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ThrowsTaglet.java line 578:
> 
>> 576:             // exceptions (i.e. Failure.ExceptionTypeNotFound | Failure.NotExceptionType),
>> 577:             // so we instantiate it with a general Failure. We then refine the specific
>> 578:             // exception being thrown, from the general exception we caught.
> 
> Really? Are you sure?  This is exactly why multi-catch was added.   Am I missing something here?

In that comment I'm talking specifically about exception-type type parameters. Consider this interface:

    public interface MyInterface {

        static <X extends Throwable> void m(...) throws X { }
    }
    
Now, you can instantiate `X` like this:

    MyInterface.<EOFException>m(...);

But if you want `m` to declare that it can throw two exceptions, you cannot instantiate `X` like this:

    MyInterface.<EOFException | FileNotFoundException>m(...);

Or like this:

    MyInterface.<EOFException, FileNotFoundException>m(...);

You have to provide one exception type. It can either be a common ancestor of `EOFException` and `FileNotFoundException`; for example, `IOException`, `Exception` or `Throwable`. Or you can pack your exceptions into something else as a cause.

Whatever you choose, you won't get transparency and compile-time checking similar to what you'd get if you had this:

    static void m(...) throws FileNotFoundException, EOFException { }

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

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