RFR: JDK-8075778: Add javadoc tag to avoid duplication of return information in simple situations. [v6]

Jonathan Gibbons jjg at openjdk.java.net
Mon Dec 7 18:37:37 UTC 2020


> 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 with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 12 additional commits since the last revision:

 - Merge remote-tracking branch 'upstream/master' into new-return
 - Update JShell to handle inline `{@return}`
 - Merge remote-tracking branch 'upstream/master' into new-return
 - fix test
 - Update for new `@return` tag
 - Merge remote-tracking branch 'upstream/master' into new-return
 - Update DocCommentParser to permit nested inline tags in specified cases: @return
 - Add default impl for new method
 - Fix test failure
 - Fix trailing whitespace in test
 - ... and 2 more: https://git.openjdk.java.net/jdk/compare/096e9a24...a25dadca

-------------

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/1355/files
  - new: https://git.openjdk.java.net/jdk/pull/1355/files/60ff9839..a25dadca

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=1355&range=05
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=1355&range=04-05

  Stats: 20689 lines in 549 files changed: 14531 ins; 4346 del; 1812 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


More information about the compiler-dev mailing list