8256917: Use combo @returns tag in java.compiler javadoc

[jddarcy]

Take advantage of upgraded dual-use @return tag.

---

Progress

• Change must not contain extraneous whitespace
• Commit message must refer to an issue
• Change must be properly reviewed

Issue

• JDK-8256917: Use combo @returns tag in java.compiler javadoc

Reviewers

• Jonathan Gibbons (@jonathan-gibbons - Reviewer)
• Iris Clark (@irisclark - Reviewer)

Download

$ git fetch https://git.openjdk.java.net/jdk pull/1708/head:pull/1708
$ git checkout pull/1708

[bridgekeeper]

👋 Welcome back darcy! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[openjdk]

@jddarcy The following label will be automatically applied to this pull request:

• compiler

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

[mlbridge]

Webrevs

• 00: Full (3ccb22b)

[jonathan-gibbons]

Pleasantly boring. Nice to see the duplication going away.

In places, I would have tweaked the phrasing or the layout, but I accept that would be out of scope for the intent of this otherwise simple change.

[openjdk]

@jddarcy This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8256917: Use combo @returns tag in java.compiler javadoc

Reviewed-by: jjg, iris

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been no new commits pushed to the master branch. If another commit should be pushed before you perform the /integrate command, your PR will be automatically rebased. If you prefer to avoid any potential automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

[irisclark]

Straightforward. I see a few minor differences (e.g. "otherwise returns X" -> "otherwise X"), but nothing significant.

Fantastic use of the new @returns tag. I look forward to seeing it used across the JDK.

[jddarcy]

Pleasantly boring. Nice to see the duplication going away.

In places, I would have tweaked the phrasing or the layout, but I accept that would be out of scope for the intent of this otherwise simple change.

Pleasantly boring. Nice to see the duplication going away.

The feature is working as intended :-)

In places, I would have tweaked the phrasing or the layout, but I accept that would be out of scope for the intent of this otherwise simple change.

Right; this was a first pass over the JSR 269 API to apply new upgraded @return tag. Fuller use could be made to DRY-out the API on subsequent passes. If I was writing the spec for this API from scratch, I'd incorporate the new facility to being with.

[jddarcy]

Straightforward. I see a few minor differences (e.g. "otherwise returns X" -> "otherwise X"), but nothing significant.

Yes; I didn't limit my pass over the API to cases where there was strict duplication, near duplication was fair game too :-) From an offline specdiff, there weren't any unexpected changes and most of the individual code diffs didn't lead to spec diffs.

Fantastic use of the new @returns tag. I look forward to seeing it used across the JDK.

Kudos to @jonathan-gibbons and the javadoc team for getting this feature in!

[jddarcy]

/integrate

[openjdk]

@jddarcy Pushed as commit 2a62d5d.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.