On Fri, 13 Sep 2024 02:47:18 GMT, Joe Darcy <da...@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
