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.
This pull request has now been integrated.
Changeset: 374193b6
Author: Pavel Rappo <[email protected]>
URL:
https://git.openjdk.java.net/jdk/commit/374193b6d2465a356941f9588a0ccf6d97cb76f6
Stats: 20 lines in 2 files changed: 14 ins; 0 del; 6 mod
8283041: [javadoc] Crashes using {@return} with @param
Reviewed-by: jjg
-------------
PR: https://git.openjdk.java.net/jdk/pull/7788
