-
Enhancement
-
Resolution: Fixed
-
P4
-
9
-
b28
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.
/**
* 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.
- blocks
-
JDK-8256917 Use combo @returns tag in java.compiler javadoc
- Resolved
- csr for
-
JDK-8256804 Add javadoc tag to avoid duplication of return information in simple situations.
- Closed
- duplicates
-
JDK-8229111 Allow omitting method summary when @return is present
- Closed