From 9d1aab7049c4677d54b5c01d8e257b508e1adf7d Mon Sep 17 00:00:00 2001 From: Nickita Khylkouski Date: Thu, 5 Feb 2026 09:35:04 -0800 Subject: [PATCH] Document `requireNonNullElseGet` in `firstNonNull` Javadoc. Fixes https://github.com/google/guava/pull/6283 Fixes https://github.com/google/guava/pull/8196 RELNOTES=n/a PiperOrigin-RevId: 865986396 --- .../com/google/common/base/MoreObjects.java | 42 ++++++++++--------- .../com/google/common/base/MoreObjects.java | 42 ++++++++++--------- 2 files changed, 44 insertions(+), 40 deletions(-) diff --git a/android/guava/src/com/google/common/base/MoreObjects.java b/android/guava/src/com/google/common/base/MoreObjects.java index 064bb5d699ef..2da58978f29a 100644 --- a/android/guava/src/com/google/common/base/MoreObjects.java +++ b/android/guava/src/com/google/common/base/MoreObjects.java @@ -22,11 +22,12 @@ import java.util.Arrays; import java.util.Collection; import java.util.Map; +import java.util.Objects; import org.jspecify.annotations.Nullable; /** * Helper functions that operate on any {@code Object}, and are not already provided in {@link - * java.util.Objects}. + * Objects}. * *

See the Guava User Guide on writing {@code Object} @@ -50,12 +51,13 @@ public final class MoreObjects { * lazy evaluation of the fallback instance, using {@link Optional#or(Supplier) * first.or(supplier)}. * - *

Java 9 users: use {@code java.util.Objects.requireNonNullElse(first, second)} - * instead. + *

Java 9 users: use {@link Objects#requireNonNullElse} instead. For lazy evaluation of + * the fallback, use {@link Objects#requireNonNullElseGet Objects.requireNonNullElseGet(first, () + * -> second)}}. * * @return {@code first} if it is non-null; otherwise {@code second} if it is non-null * @throws NullPointerException if both {@code first} and {@code second} are null - * @since 18.0 (since 3.0 as {@code Objects.firstNonNull()}). + * @since 18.0 (since 3.0 as {@code Objects.firstNonNull}). */ public static T firstNonNull(@Nullable T first, @Nullable T second) { if (first != null) { @@ -105,7 +107,7 @@ public static T firstNonNull(@Nullable T first, @Nullable T second) { * * @param self the object to generate the string for (typically {@code this}), used only for its * class name - * @since 18.0 (since 2.0 as {@code Objects.toStringHelper()}). + * @since 18.0 (since 2.0 as {@code Objects.toStringHelper}). */ public static ToStringHelper toStringHelper(Object self) { return new ToStringHelper(self.getClass().getSimpleName()); @@ -119,7 +121,7 @@ public static ToStringHelper toStringHelper(Object self) { *

Note that in GWT, class names are often obfuscated. * * @param clazz the {@link Class} of the instance - * @since 18.0 (since 7.0 as {@code Objects.toStringHelper()}). + * @since 18.0 (since 7.0 as {@code Objects.toStringHelper}). */ public static ToStringHelper toStringHelper(Class clazz) { return new ToStringHelper(clazz.getSimpleName()); @@ -131,7 +133,7 @@ public static ToStringHelper toStringHelper(Class clazz) { * Object#getClass()}. * * @param className the name of the instance type - * @since 18.0 (since 7.0 as {@code Objects.toStringHelper()}). + * @since 18.0 (since 7.0 as {@code Objects.toStringHelper}). */ public static ToStringHelper toStringHelper(String className) { return new ToStringHelper(className); @@ -160,7 +162,7 @@ private ToStringHelper(String className) { * value. The order of calling this method, relative to the {@code add()}/{@code addValue()} * methods, is not significant. * - * @since 18.0 (since 12.0 as {@code Objects.ToStringHelper.omitNullValues()}). + * @since 18.0 (since 12.0 as {@code Objects.ToStringHelper.omitNullValues}). */ @CanIgnoreReturnValue public ToStringHelper omitNullValues() { @@ -199,7 +201,7 @@ public ToStringHelper add(String name, @Nullable Object value) { /** * Adds a name/value pair to the formatted output in {@code name=value} format. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}). */ @CanIgnoreReturnValue public ToStringHelper add(String name, boolean value) { @@ -209,7 +211,7 @@ public ToStringHelper add(String name, boolean value) { /** * Adds a name/value pair to the formatted output in {@code name=value} format. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}). */ @CanIgnoreReturnValue public ToStringHelper add(String name, char value) { @@ -219,7 +221,7 @@ public ToStringHelper add(String name, char value) { /** * Adds a name/value pair to the formatted output in {@code name=value} format. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}). */ @CanIgnoreReturnValue public ToStringHelper add(String name, double value) { @@ -229,7 +231,7 @@ public ToStringHelper add(String name, double value) { /** * Adds a name/value pair to the formatted output in {@code name=value} format. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}). */ @CanIgnoreReturnValue public ToStringHelper add(String name, float value) { @@ -239,7 +241,7 @@ public ToStringHelper add(String name, float value) { /** * Adds a name/value pair to the formatted output in {@code name=value} format. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}). */ @CanIgnoreReturnValue public ToStringHelper add(String name, int value) { @@ -249,7 +251,7 @@ public ToStringHelper add(String name, int value) { /** * Adds a name/value pair to the formatted output in {@code name=value} format. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}). */ @CanIgnoreReturnValue public ToStringHelper add(String name, long value) { @@ -273,7 +275,7 @@ public ToStringHelper addValue(@Nullable Object value) { *

It is strongly encouraged to use {@link #add(String, boolean)} instead and give value a * readable name. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}). */ @CanIgnoreReturnValue public ToStringHelper addValue(boolean value) { @@ -286,7 +288,7 @@ public ToStringHelper addValue(boolean value) { *

It is strongly encouraged to use {@link #add(String, char)} instead and give value a * readable name. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}). */ @CanIgnoreReturnValue public ToStringHelper addValue(char value) { @@ -299,7 +301,7 @@ public ToStringHelper addValue(char value) { *

It is strongly encouraged to use {@link #add(String, double)} instead and give value a * readable name. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}). */ @CanIgnoreReturnValue public ToStringHelper addValue(double value) { @@ -312,7 +314,7 @@ public ToStringHelper addValue(double value) { *

It is strongly encouraged to use {@link #add(String, float)} instead and give value a * readable name. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}). */ @CanIgnoreReturnValue public ToStringHelper addValue(float value) { @@ -325,7 +327,7 @@ public ToStringHelper addValue(float value) { *

It is strongly encouraged to use {@link #add(String, int)} instead and give value a * readable name. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}). */ @CanIgnoreReturnValue public ToStringHelper addValue(int value) { @@ -338,7 +340,7 @@ public ToStringHelper addValue(int value) { *

It is strongly encouraged to use {@link #add(String, long)} instead and give value a * readable name. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}). */ @CanIgnoreReturnValue public ToStringHelper addValue(long value) { diff --git a/guava/src/com/google/common/base/MoreObjects.java b/guava/src/com/google/common/base/MoreObjects.java index 76f3eee1bf85..2286839627f6 100644 --- a/guava/src/com/google/common/base/MoreObjects.java +++ b/guava/src/com/google/common/base/MoreObjects.java @@ -22,6 +22,7 @@ import java.util.Arrays; import java.util.Collection; import java.util.Map; +import java.util.Objects; import java.util.OptionalDouble; import java.util.OptionalInt; import java.util.OptionalLong; @@ -29,7 +30,7 @@ /** * Helper functions that operate on any {@code Object}, and are not already provided in {@link - * java.util.Objects}. + * Objects}. * *

See the Guava User Guide on writing {@code Object} @@ -53,12 +54,13 @@ public final class MoreObjects { * lazy evaluation of the fallback instance, using {@link Optional#or(Supplier) * first.or(supplier)}. * - *

Java 9 users: use {@code java.util.Objects.requireNonNullElse(first, second)} - * instead. + *

Java 9 users: use {@link Objects#requireNonNullElse} instead. For lazy evaluation of + * the fallback, use {@link Objects#requireNonNullElseGet Objects.requireNonNullElseGet(first, () + * -> second)}}. * * @return {@code first} if it is non-null; otherwise {@code second} if it is non-null * @throws NullPointerException if both {@code first} and {@code second} are null - * @since 18.0 (since 3.0 as {@code Objects.firstNonNull()}). + * @since 18.0 (since 3.0 as {@code Objects.firstNonNull}). */ public static T firstNonNull(@Nullable T first, @Nullable T second) { if (first != null) { @@ -108,7 +110,7 @@ public static T firstNonNull(@Nullable T first, @Nullable T second) { * * @param self the object to generate the string for (typically {@code this}), used only for its * class name - * @since 18.0 (since 2.0 as {@code Objects.toStringHelper()}). + * @since 18.0 (since 2.0 as {@code Objects.toStringHelper}). */ public static ToStringHelper toStringHelper(Object self) { return new ToStringHelper(self.getClass().getSimpleName()); @@ -122,7 +124,7 @@ public static ToStringHelper toStringHelper(Object self) { *

Note that in GWT, class names are often obfuscated. * * @param clazz the {@link Class} of the instance - * @since 18.0 (since 7.0 as {@code Objects.toStringHelper()}). + * @since 18.0 (since 7.0 as {@code Objects.toStringHelper}). */ public static ToStringHelper toStringHelper(Class clazz) { return new ToStringHelper(clazz.getSimpleName()); @@ -134,7 +136,7 @@ public static ToStringHelper toStringHelper(Class clazz) { * Object#getClass()}. * * @param className the name of the instance type - * @since 18.0 (since 7.0 as {@code Objects.toStringHelper()}). + * @since 18.0 (since 7.0 as {@code Objects.toStringHelper}). */ public static ToStringHelper toStringHelper(String className) { return new ToStringHelper(className); @@ -163,7 +165,7 @@ private ToStringHelper(String className) { * value. The order of calling this method, relative to the {@code add()}/{@code addValue()} * methods, is not significant. * - * @since 18.0 (since 12.0 as {@code Objects.ToStringHelper.omitNullValues()}). + * @since 18.0 (since 12.0 as {@code Objects.ToStringHelper.omitNullValues}). */ @CanIgnoreReturnValue public ToStringHelper omitNullValues() { @@ -202,7 +204,7 @@ public ToStringHelper add(String name, @Nullable Object value) { /** * Adds a name/value pair to the formatted output in {@code name=value} format. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}). */ @CanIgnoreReturnValue public ToStringHelper add(String name, boolean value) { @@ -212,7 +214,7 @@ public ToStringHelper add(String name, boolean value) { /** * Adds a name/value pair to the formatted output in {@code name=value} format. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}). */ @CanIgnoreReturnValue public ToStringHelper add(String name, char value) { @@ -222,7 +224,7 @@ public ToStringHelper add(String name, char value) { /** * Adds a name/value pair to the formatted output in {@code name=value} format. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}). */ @CanIgnoreReturnValue public ToStringHelper add(String name, double value) { @@ -232,7 +234,7 @@ public ToStringHelper add(String name, double value) { /** * Adds a name/value pair to the formatted output in {@code name=value} format. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}). */ @CanIgnoreReturnValue public ToStringHelper add(String name, float value) { @@ -242,7 +244,7 @@ public ToStringHelper add(String name, float value) { /** * Adds a name/value pair to the formatted output in {@code name=value} format. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}). */ @CanIgnoreReturnValue public ToStringHelper add(String name, int value) { @@ -252,7 +254,7 @@ public ToStringHelper add(String name, int value) { /** * Adds a name/value pair to the formatted output in {@code name=value} format. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}). */ @CanIgnoreReturnValue public ToStringHelper add(String name, long value) { @@ -276,7 +278,7 @@ public ToStringHelper addValue(@Nullable Object value) { *

It is strongly encouraged to use {@link #add(String, boolean)} instead and give value a * readable name. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}). */ @CanIgnoreReturnValue public ToStringHelper addValue(boolean value) { @@ -289,7 +291,7 @@ public ToStringHelper addValue(boolean value) { *

It is strongly encouraged to use {@link #add(String, char)} instead and give value a * readable name. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}). */ @CanIgnoreReturnValue public ToStringHelper addValue(char value) { @@ -302,7 +304,7 @@ public ToStringHelper addValue(char value) { *

It is strongly encouraged to use {@link #add(String, double)} instead and give value a * readable name. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}). */ @CanIgnoreReturnValue public ToStringHelper addValue(double value) { @@ -315,7 +317,7 @@ public ToStringHelper addValue(double value) { *

It is strongly encouraged to use {@link #add(String, float)} instead and give value a * readable name. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}). */ @CanIgnoreReturnValue public ToStringHelper addValue(float value) { @@ -328,7 +330,7 @@ public ToStringHelper addValue(float value) { *

It is strongly encouraged to use {@link #add(String, int)} instead and give value a * readable name. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}). */ @CanIgnoreReturnValue public ToStringHelper addValue(int value) { @@ -341,7 +343,7 @@ public ToStringHelper addValue(int value) { *

It is strongly encouraged to use {@link #add(String, long)} instead and give value a * readable name. * - * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}). + * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}). */ @CanIgnoreReturnValue public ToStringHelper addValue(long value) {