RFR: JDK-8310571: Use inline @return tag on java.util.Objects

[Pavel Rappo]

On Thu, 22 Jun 2023 00:19:03 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> Small cleanup, minor differences in the wording of portions of toString(Object, String), nonNull(Object), requireNonNullElse, and requireNonNullElseGet.

Thanks for doing this, Joe. It seems that I have made multiple comments on the same issue. It makes me wonder if that isn't an issue at all, but is a deliberate choice made in this PR.

src/java.base/share/classes/java/util/Objects.java line 145:

> 143:      * {@return the result of calling {@code toString} on the first
> 144:      * argument if the first argument is not {@code null} and returns
> 145:      * the second argument otherwise}

This "returns" in "and returns" feels non-DRY and brittle. We enclosed that word in `{@return}` already. Maybe we could use the wording from the original `@return` to avoid the verb altogether?

This is of course, a personal opinion.

src/java.base/share/classes/java/util/Objects.java line 251:

> 249: 
> 250:     /**
> 251:      * {@return {@code true} if the provided reference is {@code

See my previous comment on the "returns" verb in the doc comment for toString(Object, String). Here (IMO), you picked the better of the two options.

src/java.base/share/classes/java/util/Objects.java line 284:

> 282:     /**
> 283:      * {@return the first argument if it is non-{@code null} and
> 284:      * otherwise returns the non-{@code null} second argument}

Same comment for "returns".

src/java.base/share/classes/java/util/Objects.java line 300:

> 298:     /**
> 299:      * {@return the first argument if it is non-{@code null} and otherwise
> 300:      * returns the non-{@code null} value of {@code supplier.get()}}

Same.

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

PR Review: https://git.openjdk.org/jdk/pull/14608#pullrequestreview-1492911171
PR Review Comment: https://git.openjdk.org/jdk/pull/14608#discussion_r1238347052
PR Review Comment: https://git.openjdk.org/jdk/pull/14608#discussion_r1238367383
PR Review Comment: https://git.openjdk.org/jdk/pull/14608#discussion_r1238370870
PR Review Comment: https://git.openjdk.org/jdk/pull/14608#discussion_r1238371975