Steer users of newMultimap and friends toward MultimapBuilder.

RELNOTES=n/a
PiperOrigin-RevId: 738165097

Author: cpovirk

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

@@ -173,7 +173,9 @@ private Multimaps() {}
 
   /**
    * Creates a new {@code Multimap} backed by {@code map}, whose internal value collections are
-   * generated by {@code factory}.
+   * generated by {@code factory}. Most users should prefer {@link MultimapBuilder}, though a small
+   * number of users will need this method to cover map or collection types that {@link
+   * MultimapBuilder} does not support.
    *
    * <p><b>Warning: do not use</b> this method when the collections returned by {@code factory}
    * implement either {@link List} or {@code Set}! Use the more specific method {@link
@@ -296,7 +298,9 @@ private void readObject(ObjectInputStream stream) throws IOException, ClassNotFo
 
   /**
    * Creates a new {@code ListMultimap} that uses the provided map and factory. It can generate a
-   * multimap based on arbitrary {@link Map} and {@link List} classes.
+   * multimap based on arbitrary {@link Map} and {@link List} classes. Most users should prefer
+   * {@link MultimapBuilder}, though a small number of users will need this method to cover map or
+   * collection types that {@link MultimapBuilder} does not support.
    *
    * <p>The {@code factory}-generated and {@code map} classes determine the multimap iteration
    * order. They also specify the behavior of the {@code equals}, {@code hashCode}, and {@code
@@ -380,7 +384,9 @@ private void readObject(ObjectInputStream stream) throws IOException, ClassNotFo
 
   /**
    * Creates a new {@code SetMultimap} that uses the provided map and factory. It can generate a
-   * multimap based on arbitrary {@link Map} and {@link Set} classes.
+   * multimap based on arbitrary {@link Map} and {@link Set} classes. Most users should prefer
+   * {@link MultimapBuilder}, though a small number of users will need this method to cover map or
+   * collection types that {@link MultimapBuilder} does not support.
    *
    * <p>The {@code factory}-generated and {@code map} classes determine the multimap iteration
    * order. They also specify the behavior of the {@code equals}, {@code hashCode}, and {@code

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

@@ -172,7 +172,9 @@ private Multimaps() {}
 
   /**
    * Creates a new {@code Multimap} backed by {@code map}, whose internal value collections are
-   * generated by {@code factory}.
+   * generated by {@code factory}. Most users should prefer {@link MultimapBuilder}, though a small
+   * number of users will need this method to cover map or collection types that {@link
+   * MultimapBuilder} does not support.
    *
    * <p><b>Warning: do not use</b> this method when the collections returned by {@code factory}
    * implement either {@link List} or {@code Set}! Use the more specific method {@link
@@ -295,7 +297,9 @@ private void readObject(ObjectInputStream stream) throws IOException, ClassNotFo
 
   /**
    * Creates a new {@code ListMultimap} that uses the provided map and factory. It can generate a
-   * multimap based on arbitrary {@link Map} and {@link List} classes.
+   * multimap based on arbitrary {@link Map} and {@link List} classes. Most users should prefer
+   * {@link MultimapBuilder}, though a small number of users will need this method to cover map or
+   * collection types that {@link MultimapBuilder} does not support.
    *
    * <p>The {@code factory}-generated and {@code map} classes determine the multimap iteration
    * order. They also specify the behavior of the {@code equals}, {@code hashCode}, and {@code
@@ -379,7 +383,9 @@ private void readObject(ObjectInputStream stream) throws IOException, ClassNotFo
 
   /**
    * Creates a new {@code SetMultimap} that uses the provided map and factory. It can generate a
-   * multimap based on arbitrary {@link Map} and {@link Set} classes.
+   * multimap based on arbitrary {@link Map} and {@link Set} classes. Most users should prefer
+   * {@link MultimapBuilder}, though a small number of users will need this method to cover map or
+   * collection types that {@link MultimapBuilder} does not support.
    *
    * <p>The {@code factory}-generated and {@code map} classes determine the multimap iteration
    * order. They also specify the behavior of the {@code equals}, {@code hashCode}, and {@code