On Mon, 24 Oct 2022 20:23:52 GMT, Jonathan Gibbons <[email protected]> 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
