Explicitly specify that some returned values are serializable.

Also specify under what circumstances. We don't spell this out for absolutely
everything. For example, `ImmutableList` implements `Serializable`, so you
would expect that an `ImmutableList` would be serializable if all of its
elements are, and you would be right.

RELNOTES=n/a
PiperOrigin-RevId: 496461811

android/guava/src/com/google/common/base/CaseFormat.java

@@ -151,7 +151,8 @@ String convert(CaseFormat format, String s) {
   }
 
   /**
-   * Returns a {@code Converter} that converts strings from this format to {@code targetFormat}.
+   * Returns a serializable {@code Converter} that converts strings from this format to {@code
+   * targetFormat}.
    *
    * @since 16.0
    */

android/guava/src/com/google/common/base/Enums.java

@@ -98,10 +98,10 @@ static <T extends Enum<T>> Map<String, WeakReference<? extends Enum<?>>> getEnum
   }
 
   /**
-   * Returns a converter that converts between strings and {@code enum} values of type {@code
-   * enumClass} using {@link Enum#valueOf(Class, String)} and {@link Enum#name()}. The converter
-   * will throw an {@code IllegalArgumentException} if the argument is not the name of any enum
-   * constant in the specified enum.
+   * Returns a serializable converter that converts between strings and {@code enum} values of type
+   * {@code enumClass} using {@link Enum#valueOf(Class, String)} and {@link Enum#name()}. The
+   * converter will throw an {@code IllegalArgumentException} if the argument is not the name of any
+   * enum constant in the specified enum.
    *
    * @since 16.0
    */

android/guava/src/com/google/common/base/Equivalence.java

@@ -151,6 +151,9 @@ public final <F> Equivalence<F> onResultOf(Function<? super F, ? extends @Nullab
    * Object.equals()} such that {@code wrap(a).equals(wrap(b))} if and only if {@code equivalent(a,
    * b)}.
    *
+   * <p>The returned object is serializable if both this {@code Equivalence} and {@code reference}
+   * are serializable (including when {@code reference} is null).
+   *
    * @since 10.0
    */
   public final <S extends @Nullable T> Wrapper<S> wrap(@ParametricNullness S reference) {
@@ -255,6 +258,8 @@ public String toString() {
    * <p>Note that this method performs a similar function for equivalences as {@link
    * com.google.common.collect.Ordering#lexicographical} does for orderings.
    *
+   * <p>The returned object is serializable if this object is serializable.
+   *
    * @since 10.0
    */
   @GwtCompatible(serializable = true)

android/guava/src/com/google/common/base/Optional.java

@@ -52,6 +52,9 @@
  * <p>This class is not intended as a direct analogue of any existing "option" or "maybe" construct
  * from other programming environments, though it may bear some similarities.
  *
+ * <p>An instance of this class is serializable if its reference is absent or is a serializable
+ * object.
+ *
  * <p><b>Comparison to {@code java.util.Optional} (JDK 8 and higher):</b> A new {@code Optional}
  * class was added for Java 8. The two classes are extremely similar, but incompatible (they cannot
  * share a common supertype). <i>All</i> known differences are listed either here or with the

android/guava/src/com/google/common/base/Suppliers.java

@@ -96,7 +96,7 @@ public String toString() {
    * <p>The returned supplier is thread-safe. The delegate's {@code get()} method will be invoked at
    * most once unless the underlying {@code get()} throws an exception. The supplier's serialized
    * form does not contain the cached value, which will be recalculated when {@code get()} is called
-   * on the reserialized instance.
+   * on the deserialized instance.
    *
    * <p>When the underlying delegate throws an exception then this memoizing supplier will keep
    * delegating calls until it returns valid data.

android/guava/src/com/google/common/cache/CacheLoader.java

@@ -133,6 +133,8 @@ public Map<K, V> loadAll(Iterable<? extends K> keys) throws Exception {
    * reloading or bulk loading. This is most useful when you can pass a lambda expression. Otherwise
    * it is useful mostly when you already have an existing function instance.
    *
+   * <p>The returned object is serializable if {@code function} is serializable.
+   *
    * @param function the function to be used for loading values; must never return {@code null}
    * @return a cache loader that loads values by passing each key to {@code function}
    */
@@ -145,6 +147,8 @@ public static <K, V> CacheLoader<K, V> from(Function<K, V> function) {
    * to create a <i>new</i> supplier just to pass it in here; just subclass {@code CacheLoader} and
    * implement {@link #load load} instead.
    *
+   * <p>The returned object is serializable if {@code supplier} is serializable.
+   *
    * @param supplier the supplier to be used for loading values; must never return {@code null}
    * @return a cache loader that loads values by calling {@link Supplier#get}, irrespective of the
    *     key

android/guava/src/com/google/common/collect/DiscreteDomain.java

@@ -50,6 +50,9 @@ public abstract class DiscreteDomain<C extends Comparable> {
   /**
    * Returns the discrete domain for values of type {@code Integer}.
    *
+   * <p>This method always returns the same object. That object is serializable; deserializing it
+   * results in the same object too.
+   *
    * @since 14.0 (since 10.0 as {@code DiscreteDomains.integers()})
    */
   public static DiscreteDomain<Integer> integers() {
@@ -113,6 +116,9 @@ public String toString() {
   /**
    * Returns the discrete domain for values of type {@code Long}.
    *
+   * <p>This method always returns the same object. That object is serializable; deserializing it
+   * results in the same object too.
+   *
    * @since 14.0 (since 10.0 as {@code DiscreteDomains.longs()})
    */
   public static DiscreteDomain<Long> longs() {
@@ -187,6 +193,9 @@ public String toString() {
   /**
    * Returns the discrete domain for values of type {@code BigInteger}.
    *
+   * <p>This method always returns the same object. That object is serializable; deserializing it
+   * results in the same object too.
+   *
    * @since 15.0
    */
   public static DiscreteDomain<BigInteger> bigIntegers() {

android/guava/src/com/google/common/collect/Ordering.java

@@ -171,6 +171,8 @@ public static <C extends Comparable> Ordering<C> natural() {
    * to pass it in here. Instead, simply subclass {@code Ordering} and implement its {@code compare}
    * method directly.
    *
+   * <p>The returned object is serializable if {@code comparator} is serializable.
+   *
    * <p><b>Java 8 users:</b> this class is now obsolete as explained in the class documentation, so
    * there is no need to use this method.
    *
@@ -410,6 +412,8 @@ public <S extends T> Ordering<S> reverse() {
    * Returns an ordering that treats {@code null} as less than all other values and uses {@code
    * this} to compare non-null values.
    *
+   * <p>The returned object is serializable if this object is serializable.
+   *
    * <p><b>Java 8 users:</b> Use {@code Comparator.nullsFirst(thisComparator)} instead.
    */
   // type parameter <S> lets us avoid the extra <String> in statements like:
@@ -423,6 +427,8 @@ public <S extends T> Ordering<S> reverse() {
    * Returns an ordering that treats {@code null} as greater than all other values and uses this
    * ordering to compare non-null values.
    *
+   * <p>The returned object is serializable if this object is serializable.
+   *
    * <p><b>Java 8 users:</b> Use {@code Comparator.nullsLast(thisComparator)} instead.
    */
   // type parameter <S> lets us avoid the extra <String> in statements like:
@@ -463,6 +469,9 @@ public <S extends T> Ordering<S> reverse() {
    * <p>An ordering produced by this method, or a chain of calls to this method, is equivalent to
    * one created using {@link Ordering#compound(Iterable)} on the same component comparators.
    *
+   * <p>The returned object is serializable if this object and {@code secondaryComparator} are both
+   * serializable.
+   *
    * <p><b>Java 8 users:</b> Use {@code thisComparator.thenComparing(secondaryComparator)} instead.
    * Depending on what {@code secondaryComparator} is, one of the other overloads of {@code
    * thenComparing} may be even more useful.
@@ -481,6 +490,8 @@ public <U extends T> Ordering<U> compound(Comparator<? super U> secondaryCompara
    * <p>The returned ordering is equivalent to that produced using {@code
    * Ordering.from(comp1).compound(comp2).compound(comp3) . . .}.
    *
+   * <p>The returned object is serializable if each of the {@code comparators} is serializable.
+   *
    * <p><b>Warning:</b> Supplying an argument with undefined iteration order, such as a {@link
    * HashSet}, will produce non-deterministic results.
    *

android/guava/src/com/google/common/collect/Range.java

@@ -106,6 +106,7 @@
  *       <i>P</i> if, for all ranges {@code b} also having property <i>P</i>, {@code a.encloses(b)}.
  *       Likewise, {@code a} is <i>minimal</i> when {@code b.encloses(a)} for all {@code b} having
  *       property <i>P</i>. See, for example, the definition of {@link #intersection intersection}.
+ *   <li>A {@code Range} is serializable if it has no bounds, or if each bound is serializable.
  * </ul>
  *
  * <h3>Further reading</h3>

android/guava/src/com/google/common/primitives/Booleans.java

@@ -364,6 +364,8 @@ public static boolean[] toArray(Collection<Boolean> collection) {
    * <p>There are at most two distinct objects in this list, {@code (Boolean) true} and {@code
    * (Boolean) false}. Java guarantees that those are always represented by the same objects.
    *
+   * <p>The returned list is serializable.
+   *
    * @param backingArray the array to back the list
    * @return a list view of the array
    */

android/guava/src/com/google/common/primitives/Bytes.java

@@ -227,6 +227,8 @@ public static byte[] toArray(Collection<? extends Number> collection) {
    * written to or read from it. For example, whether {@code list.get(0) == list.get(0)} is true for
    * the returned list is unspecified.
    *
+   * <p>The returned list is serializable.
+   *
    * @param backingArray the array to back the list
    * @return a list view of the array
    */

android/guava/src/com/google/common/primitives/Chars.java

@@ -547,6 +547,8 @@ public static void rotate(char[] array, int distance, int fromIndex, int toIndex
    * written to or read from it. For example, whether {@code list.get(0) == list.get(0)} is true for
    * the returned list is unspecified.
    *
+   * <p>The returned list is serializable.
+   *
    * @param backingArray the array to back the list
    * @return a list view of the array
    */

android/guava/src/com/google/common/primitives/Doubles.java

@@ -557,6 +557,8 @@ public static double[] toArray(Collection<? extends Number> collection) {
    * <p>The returned list may have unexpected behavior if it contains {@code NaN}, or if {@code NaN}
    * is used as a parameter to any of its methods.
    *
+   * <p>The returned list is serializable.
+   *
    * <p><b>Note:</b> when possible, you should represent your data as an {@link
    * ImmutableDoubleArray} instead, which has an {@link ImmutableDoubleArray#asList asList} view.
    *

android/guava/src/com/google/common/primitives/Floats.java

@@ -554,6 +554,8 @@ public static float[] toArray(Collection<? extends Number> collection) {
    * <p>The returned list may have unexpected behavior if it contains {@code NaN}, or if {@code NaN}
    * is used as a parameter to any of its methods.
    *
+   * <p>The returned list is serializable.
+   *
    * @param backingArray the array to back the list
    * @return a list view of the array
    */

android/guava/src/com/google/common/primitives/Ints.java

@@ -623,6 +623,8 @@ public static int[] toArray(Collection<? extends Number> collection) {
    * written to or read from it. For example, whether {@code list.get(0) == list.get(0)} is true for
    * the returned list is unspecified.
    *
+   * <p>The returned list is serializable.
+   *
    * <p><b>Note:</b> when possible, you should represent your data as an {@link ImmutableIntArray}
    * instead, which has an {@link ImmutableIntArray#asList asList} view.
    *

android/guava/src/com/google/common/primitives/Longs.java

@@ -693,6 +693,8 @@ public static long[] toArray(Collection<? extends Number> collection) {
    * written to or read from it. For example, whether {@code list.get(0) == list.get(0)} is true for
    * the returned list is unspecified.
    *
+   * <p>The returned list is serializable.
+   *
    * <p><b>Note:</b> when possible, you should represent your data as an {@link ImmutableLongArray}
    * instead, which has an {@link ImmutableLongArray#asList asList} view.
    *

android/guava/src/com/google/common/primitives/Shorts.java

@@ -599,6 +599,8 @@ public static short[] toArray(Collection<? extends Number> collection) {
    * written to or read from it. For example, whether {@code list.get(0) == list.get(0)} is true for
    * the returned list is unspecified.
    *
+   * <p>The returned list is serializable.
+   *
    * @param backingArray the array to back the list
    * @return a list view of the array
    */

android/guava/src/com/google/common/util/concurrent/AtomicLongMap.java

@@ -43,6 +43,8 @@
  * <p>Instances of this class may be used by multiple threads concurrently. All operations are
  * atomic unless otherwise noted.
  *
+ * <p>Instances of this class are serializable if the keys are serializable.
+ *
  * <p><b>Note:</b> If your values are always positive and less than 2^31, you may wish to use a
  * {@link com.google.common.collect.Multiset} such as {@link
  * com.google.common.collect.ConcurrentHashMultiset} instead.

guava/src/com/google/common/base/CaseFormat.java

@@ -151,7 +151,8 @@ String convert(CaseFormat format, String s) {
   }
 
   /**
-   * Returns a {@code Converter} that converts strings from this format to {@code targetFormat}.
+   * Returns a serializable {@code Converter} that converts strings from this format to {@code
+   * targetFormat}.
    *
    * @since 16.0
    */

guava/src/com/google/common/base/Enums.java

@@ -98,10 +98,10 @@ static <T extends Enum<T>> Map<String, WeakReference<? extends Enum<?>>> getEnum
   }
 
   /**
-   * Returns a converter that converts between strings and {@code enum} values of type {@code
-   * enumClass} using {@link Enum#valueOf(Class, String)} and {@link Enum#name()}. The converter
-   * will throw an {@code IllegalArgumentException} if the argument is not the name of any enum
-   * constant in the specified enum.
+   * Returns a serializable converter that converts between strings and {@code enum} values of type
+   * {@code enumClass} using {@link Enum#valueOf(Class, String)} and {@link Enum#name()}. The
+   * converter will throw an {@code IllegalArgumentException} if the argument is not the name of any
+   * enum constant in the specified enum.
    *
    * @since 16.0
    */

guava/src/com/google/common/base/Equivalence.java

@@ -163,6 +163,9 @@ public final <F> Equivalence<F> onResultOf(Function<? super F, ? extends @Nullab
    * Object.equals()} such that {@code wrap(a).equals(wrap(b))} if and only if {@code equivalent(a,
    * b)}.
    *
+   * <p>The returned object is serializable if both this {@code Equivalence} and {@code reference}
+   * are serializable (including when {@code reference} is null).
+   *
    * @since 10.0
    */
   public final <S extends @Nullable T> Wrapper<S> wrap(@ParametricNullness S reference) {
@@ -267,6 +270,8 @@ public String toString() {
    * <p>Note that this method performs a similar function for equivalences as {@link
    * com.google.common.collect.Ordering#lexicographical} does for orderings.
    *
+   * <p>The returned object is serializable if this object is serializable.
+   *
    * @since 10.0
    */
   @GwtCompatible(serializable = true)

guava/src/com/google/common/base/Optional.java

@@ -52,6 +52,9 @@
  * <p>This class is not intended as a direct analogue of any existing "option" or "maybe" construct
  * from other programming environments, though it may bear some similarities.
  *
+ * <p>An instance of this class is serializable if its reference is absent or is a serializable
+ * object.
+ *
  * <p><b>Comparison to {@code java.util.Optional} (JDK 8 and higher):</b> A new {@code Optional}
  * class was added for Java 8. The two classes are extremely similar, but incompatible (they cannot
  * share a common supertype). <i>All</i> known differences are listed either here or with the

guava/src/com/google/common/base/Suppliers.java

@@ -96,7 +96,7 @@ public String toString() {
    * <p>The returned supplier is thread-safe. The delegate's {@code get()} method will be invoked at
    * most once unless the underlying {@code get()} throws an exception. The supplier's serialized
    * form does not contain the cached value, which will be recalculated when {@code get()} is called
-   * on the reserialized instance.
+   * on the deserialized instance.
    *
    * <p>When the underlying delegate throws an exception then this memoizing supplier will keep
    * delegating calls until it returns valid data.

guava/src/com/google/common/cache/CacheLoader.java

@@ -132,6 +132,8 @@ public Map<K, V> loadAll(Iterable<? extends K> keys) throws Exception {
    * Returns a cache loader that uses {@code function} to load keys, without supporting either
    * reloading or bulk loading. This allows creating a cache loader using a lambda expression.
    *
+   * <p>The returned object is serializable if {@code function} is serializable.
+   *
    * @param function the function to be used for loading values; must never return {@code null}
    * @return a cache loader that loads values by passing each key to {@code function}
    */
@@ -144,6 +146,8 @@ public static <K, V> CacheLoader<K, V> from(Function<K, V> function) {
    * to create a <i>new</i> supplier just to pass it in here; just subclass {@code CacheLoader} and
    * implement {@link #load load} instead.
    *
+   * <p>The returned object is serializable if {@code supplier} is serializable.
+   *
    * @param supplier the supplier to be used for loading values; must never return {@code null}
    * @return a cache loader that loads values by calling {@link Supplier#get}, irrespective of the
    *     key

guava/src/com/google/common/collect/DiscreteDomain.java

@@ -50,6 +50,9 @@ public abstract class DiscreteDomain<C extends Comparable> {
   /**
    * Returns the discrete domain for values of type {@code Integer}.
    *
+   * <p>This method always returns the same object. That object is serializable; deserializing it
+   * results in the same object too.
+   *
    * @since 14.0 (since 10.0 as {@code DiscreteDomains.integers()})
    */
   public static DiscreteDomain<Integer> integers() {
@@ -113,6 +116,9 @@ public String toString() {
   /**
    * Returns the discrete domain for values of type {@code Long}.
    *
+   * <p>This method always returns the same object. That object is serializable; deserializing it
+   * results in the same object too.
+   *
    * @since 14.0 (since 10.0 as {@code DiscreteDomains.longs()})
    */
   public static DiscreteDomain<Long> longs() {
@@ -187,6 +193,9 @@ public String toString() {
   /**
    * Returns the discrete domain for values of type {@code BigInteger}.
    *
+   * <p>This method always returns the same object. That object is serializable; deserializing it
+   * results in the same object too.
+   *
    * @since 15.0
    */
   public static DiscreteDomain<BigInteger> bigIntegers() {