On Fri, 11 Mar 2022 17:54:21 GMT, Pavel Rappo <pra...@openjdk.org> wrote:
>> The inline `{@return}` tag is relatively new and will require developers to
>> change their habits. According to the
>> [specification](https://docs.oracle.com/en/java/javase/17/docs/specs/javadoc/doc-comment-spec.html#return),
>> the inline version of `@return` "may only occur at the beginning of a
>> method's description".
>>
>> When used like in the description of the issue, the tag technically belongs
>> to the block `@param` tag and not to the body of the doc comment, which one
>> might think is the case. Thus, the "full body" (let alone "first sentence")
>> collection of doc nodes is empty. Hence, IndexOutOfBoundsException when
>> trying to access its first element.
>>
>> Since we don't have a method that returns the **complete** doc comment (yes,
>> "getFullBody" is a bit of a misleading name), whose first element we could
>> check against `{@return}`, I check `isEmpty()` before accessing the first
>> element.
>>
>> Interestingly, `{@summary}` (must also appear first) lint is performed
>> differently. However, I decided not to copy it since it operates on a lower
>> level of abstraction: characters and strings thereof.
>
> Pavel Rappo has updated the pull request incrementally with one additional
> commit since the last revision:
>
> Correct warning category
Marked as reviewed by jjg (Reviewer).
-------------
PR: https://git.openjdk.java.net/jdk/pull/7788
