RFR: 8285488: Improve DocFinder [v4]

[Pavel Rappo]

On Fri, 28 Oct 2022 20:57:26 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
>
> test/langtools/jdk/javadoc/doclet/testThrowsInheritanceMatching/TestExceptionTypeMatching.java line 426:
> 
>> 424:      * a method. For example, consider that for B to be a subtype of A,
>> 425:      * it is not necessary for A and B to have the same number or
>> 426:      * types of type parameters.
> 
> it's clear and well-defined; just not simple!
> `javac` can clearly do it, which means that in theory, it could be exposed in the Language Model API.

Correct. Maybe I should rephrase that along the lines that until javax.lang.model provides that functionality, JavaDoc does not support that use case. Generally, JavaDoc should not try to replicate complex parts of jdk.compiler.

The good news is that APIs where an exception-type type variable thrown by a method is not declared by that method seem rare. So much so, that as of today we don't have any such public JDK API. So we don't need that language-model functionality urgently.

On the other hand, one such API is on the horizon. Among other things, JEP 430 (String Templates (Preview)) defines an API that has this:

    public interface ValidatingProcessor<R, E extends Throwable> {
        R process(StringTemplate stringTemplate) throws E;
    }

After that API lands, eventually someone might try to write something like this in their own processor:

    /** @throws X {@inheritDoc} */
    X process(StringTemplate stringTemplate) throws X;

For now, they will get a javadoc warning.

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

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