FYI, I had a good experience taking a trial run of this patch to update
the java.compiler APIs to use the new feature. I didn't find any issues;
a specdiff comparing with and without use of the new tag didn't have any
unexpected diffs. (There were cases where small wording differences
existed and were regularized in the patch.)
After this goes back, looking forward to pushing a fix for JDK-8256917:
Use combo @returns tag in java.compiler javadoc.
Cheers,
-Joe
On 11/20/2020 4:34 PM, Jonathan Gibbons wrote:
This change extends the functionality of the `@return` tag so that it can also
be used as an inline tag in the first sentence of a description.
The goal is to be able to simplify the following common pattern:
/**
* Returns the result. Optional additional text.
* @return the result
*/
int method() {
by
/**
* {@return the result} Optional additional text.
*/
int method() {
Note:
* The inline tag may only be used at the beginning of the description. A
warning will be given if it is used elsewhere.
* The expansion of the inline tag is `Returns " _content_ `.` where _content_
is the content of the tag.
* If there is no block `@return` tag, the standard doclet will look for an
inline tag at the beginning of the description
* The inline tag can be inherited into overriding methods as if it was provided
as a block tag.
Jonathan Gibbons has updated the pull request incrementally with one additional
commit since the last revision:
Update DocCommentParser to permit nested inline tags in specified cases:
@return
-------------
Changes:
- all: https://git.openjdk.java.net/jdk/pull/1355/files
- new: https://git.openjdk.java.net/jdk/pull/1355/files/89846ff1..87edfb0c
Webrevs:
- full: https://webrevs.openjdk.java.net/?repo=jdk&pr=1355&range=02
- incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=1355&range=01-02
Stats: 88 lines in 3 files changed: 82 ins; 3 del; 3 mod
Patch: https://git.openjdk.java.net/jdk/pull/1355.diff
Fetch: git fetch https://git.openjdk.java.net/jdk pull/1355/head:pull/1355
PR: https://git.openjdk.java.net/jdk/pull/1355
