On Fri, 11 Mar 2022 15:49:06 GMT, Pavel Rappo <[email protected]> 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.
-------------
PR: https://git.openjdk.java.net/jdk/pull/7788
