On Tue, 22 Jul 2025 15:29:57 GMT, Roger Riggs <rri...@openjdk.org> wrote:
>> Absolutely. This sort of thing is always a balance between clarity and
>> conciseness. But here I think you're right so I pulled the `name` into a
>> `@param`. I dislike doing it for the return types in most cases though,
>> since that encourages duplication with the method's first sentence.
>
> The {@return 1st sentence text} can be used on the first line and javadoc
> will put the text in both places without needing duplication in the source.
> [(javadoc tag
> specification](https://docs.oracle.com/en/java/javase/22/docs/specs/javadoc/doc-comment-spec.html))
I don't think that's better because the "1st sentence text" isn't prefixed with
the word "Returns", one if a verb-phase (the action of the method) and the
other a noun phrase (the thing returned).
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/26054#discussion_r2247975975
