Bug ID: JDK-8075778 Add javadoc tag to avoid duplication of return information in simple situations.

Versions (Unresolved/Resolved/Fixed)

The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.

JDK 16
16 b28Fixed

For a simple, getFoo method, the recommended correct javadoc is

/**
 * Returns a Foo.
 * @return a Foo.
 */
Foo getFoo()

This pattern is quite redundant, tedious to maintain, and clumsy to read in the sources.

It would be preferable if a single javadoc tag, say {@Return } could be used in these situations like

/**
 * {@Returns} a Foo.
 */
Foo getFoo()

which would have the same effect as the method javadoc with a separate @return tag as above.

The use of the {@Returns} tag would be intended for simple situation where there was a direct (near) repetition of the initial sentence and the @return tag. When such repetition was not present or desirable, the {@Returns} tag should not be used.

Changeset: b29f9cd7 Author: Jonathan Gibbons <jjg@openjdk.org> Date: 2020-12-08 23:25:08 +0000 URL: https://git.openjdk.java.net/jdk/commit/b29f9cd7
08-12-2020
Thinking aloud ... We have to consider the interactions between the new usage and `{@inheritDoc}`. For this purpose, I suggest that the usage as in inline tag should be "as if" it was duplicated as an equivalent block tag.
07-10-2020
I'm happy to give this feature a test drive in the javax.lang.model docs once a prototype is available.
27-06-2020
Given that we have now have bimodal tags, the following is a suggestion: {@return <description>} expands to Returns <description> We can bikeshed over whether there should a final period in <description> or after the tag, or not at all (one will be provided automatically.) If there is no block tag for @return then the doclet will check for {@return} at the beginning of the body, before looking for an inherited tag.
27-06-2020
I would say "say" {@Returns} (however it is spelled) would have to be the first and tag and would run to the end of the first sentence. In my estimation, it would be preferable to have an {@Returns} tag rather than to allow a naked /** * @return a Foo / because the {@Returns} would allow sharing in more cases. It is common to have javadoc like /* * Returns a Foo. More detail about how the Foo is returned. Still more information about what the method does. * ... * @return a Foo */ and it would be convenient to elide the redundant @return in this situation too.
24-03-2015
Architecturally, this would be a weird tag, since the tag has an effect outside of its enclosing braces. Specifically, it sucks up some amount of the following text, and then generates an implicit block tag. Not impossible, but definitely unusual. The spec for the tag would need to include details like Can this only appear at the beginning of a doc comment? How much of the following text is "sucked up" by the {@Returns} tag? Just the rest of the (first?) sentence, or all of the text up to the first block tag? Is the tag only permitted if there is only a "first sentence"? What about alternatives? Without introducing any new tags, how about inferring the first sentence if it is missing and @return is given. /** * @return a Foo */ Foo getFoo()
24-03-2015

Blocks :	JDK-8256917 - Use combo @returns tag in java.compiler javadoc
CSR :	JDK-8256804 - Add javadoc tag to avoid duplication of return information in simple situations.
Duplicate :	JDK-8229111 - Allow omitting method summary when @return is present