Hi,
Note that the first sentence is promoted to the lists of methods,
constructors, etc.
The first sentence should *always* contain a cogent summary of the method.
$0.02, Roger
On 9/13/24 5:23 PM, Pavel Rappo wrote:
Thanks for starting this thread, Jon.
On 13 Sep 2024, at 21:50, Jonathan Gibbons <jonathan.gibb...@oracle.com> wrote:
Re: https://mail.openjdk.org/pipermail/core-libs-dev/2024-September/129508.html
This is a thread on using increasing the use of `{@return}`
In it, Pavel wrote:
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-d
ev mailing list.
I think this is a good idea to look at. Although it does not have as catchy an acronym, "Don't
Repeat Yourself" (DRY) could be extended to "Don't Make Me Read The Same text Twice"
(DMMRTSTT).
-- Jon
Reading the same text twice is arguably not as bad as not knowing it is the
same. If it's a big sentence or two, which is now possible with {@return},
you'd be comparing the text to see if you missed some detail.
Reading the same text twice is arguably not as bad as not knowing it is the
same. If it's a big sentence or two, which is now possible with {@return},
you'd be comparing the text to see if you missed some detail.
-Pavel
