On Fri, 28 Oct 2022 18:16:07 GMT, Jonathan Gibbons <j...@openjdk.org> wrote:
>> 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.
>
>> While I think it's quite clear...
>
> I guess the narrative form is _exception class_ even if the BNF form is
> `ExceptionType` !
Maybe we could simply call it _exception_? Exception _class_ excludes type
variables. Exception _name_ is too stringly-typed. Exception _type_ and
_element_ clash with liked-named entities in javax.lang.model.
Coming up with good terms is hard. FWIW, in ThrowsTaglet I consistently call
`@throws` and `@exception` exception tags.
-------------
PR: https://git.openjdk.org/jdk/pull/10746
