On Fri, 11 Mar 2022 15:53:34 GMT, Jonathan Gibbons <j...@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.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line
> 988:
>
>> 986: if (tree.isInline()) {
>> 987: DocCommentTree dct = getCurrentPath().getDocComment();
>> 988: if (dct.getFullBody().isEmpty() || tree !=
>> dct.getFullBody().get(0)) {
>
> It should not be necessary to resort to `getFullBody`. It should be enough
> to check the first sentence, but that check should not throw an exception.
I thought that getting the first sentence would unnecessarily trigger sentence
segmentation and read less clearly. But I can revert it if you like.
-------------
PR: https://git.openjdk.java.net/jdk/pull/7788
