RFR: 8283041: [javadoc] Crashes using {@return} with @param

[Jonathan Gibbons]

On Fri, 11 Mar 2022 15:49:06 GMT, Pavel Rappo <prappo at 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.

As a general comment on terminology,

In the initial version of the API, a `DocCommentTree` was split into 3 parts:
1. the "first sentence"
2. the "body"
3. the block tags.

The split between "first sentence" and "body" eventually caused difficulties, because it lost the whitespace between them. So we retrofitted "full body" as the compound of "first sentence and body".

In a different reality, it would have been better to use the name `body" to refer to all the content before the block tags, and to have some other name for the content between the first sentence and the block tags, which (with hindsight) is typically a less interesting abstraction.   The rationale is that we did not want "overlap" between nodes of the tree.

-------------

PR: https://git.openjdk.java.net/jdk/pull/7788