RFR: 8340082: Use inline return tag in java.base

[Pavel Rappo]

On Fri, 13 Sep 2024 02:47:18 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> Candidates for this refactoring were found programmatically; the program to find candidates is in a comment on the bug.

Thanks, Joe. This looks good, especially considering that the change was produced with the help of a quick-and-dirty, regex-based script. This change is certainly enough to spread awareness of this relatively new javadoc feature.

I remember I had a more involved script that used `javax.lang.model` and string similarity metrics. That script captured a lot more candidates for `{@return}`. But on the other hand, once you start considering non-exact matches, it requires human judgement and increases review effort.

---

Separately, this PR has helped me put a finger on what I __don't__ like about `{@return}`. What I don't like is the generated HTML. `{@return}` saves mental effort when reading raw javadoc in source, but it provides no similar service to the reader of the final, HTML form. Maybe it's just me, but it looks needlessly bloated and silly:

<img width="201" alt="browser screenshot of javax.lang.model.element.AnnotationValue#getValue" src="https://github.com/user-attachments/assets/1a7ee92f-7006-4b09-bc50-e23d9148c3ad">

Maybe if a method's main description consisted only of `{@return}`, we could skip the first sentence in the "Method Details" section and just output `Returns:`? Any further discussion should happen on the javadoc-dev mailing list.

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

Marked as reviewed by prappo (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/20981#pullrequestreview-2302744094