RFR: 8285488: Improve DocFinder [v3]

[Pavel Rappo]

On Mon, 24 Oct 2022 20:23:52 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   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.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties line 121:
> 
>> 119: doclet.UnknownTagLowercase={0} is an unknown tag -- same as a known tag except for case.
>> 120: doclet.inheritDocWithinInappropriateTag=@inheritDoc cannot be used within this tag
>> 121: doclet.inheritDocNoDoc=overridden methods do not document exception type {0}
> 
> we should check with Dan/Alex for the right terminology here; my best understanding is that we now use `exception class`.  Bottom line, we should follow JLS.

While I think it's quite clear, I agree on double-checking.

What `ThrowsTaglet` is interested in is the argument to the `@throws` tag and the element that can be mentioned in the `throws` clause. While JLS does not specify javadoc tags, it specifies the `throws` clause.

Here's what JLS says about the `throws` clause:

     * 8.4.6 Method Throws
     *
     *   Throws:
     *     throws ExceptionTypeList
     *
     *   ExceptionTypeList:
     *     ExceptionType {, ExceptionType}
     *
     *   ExceptionType:
     *     ClassType
     *     TypeVariable
     *
     *   It is a compile-time error if an ExceptionType mentioned in a throws
     *   clause is not a subtype (4.10) of Throwable.
     *
     *   Type variables are allowed in a throws clause even though they are
     *   not allowed in a catch clause (14.20).

So, the `throws` clause can mention either an exception class or a type variable with the upper bound of `Throwable`. 

Here's what JLS says about exception classes:

     * 11.1.1 The Kinds of Exceptions
     *
     *   Throwable and all its subclasses are, collectively, the exception
     *   classes.

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

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