mention target::contains in Predicates.in()'s javadocs.

RELNOTES=n/a
PiperOrigin-RevId: 742818259

Author: kluever

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

@@ -208,6 +208,19 @@ public static Predicate<Class<?>> subtypeOf(Class<?> clazz) {
    * helps prevent bugs. This approach doesn't block any potential users since it is always possible
    * to use {@code Predicates.<Object>in()}.
    *
+   * <p>You may prefer to use a method reference (e.g., {@code target::contains}) instead of this
+   * method. However, there are some subtle considerations:
+   *
+   * <ul>
+   *   <li>The {@link Predicate} returned by this method is {@link Serializable}.
+   *   <li>The {@link Predicate} returned by this method catches {@link ClassCastException} and
+   *       {@link NullPointerException}.
+   *   <li>Code that chains multiple predicates together (especially negations) may be more readable
+   *       using this method. For example, {@code not(in(target))} is generally more readable than
+   *       {@code not(target::contains)}.
+   *   <li>This method's name conflicts with Kotlin's {@code in} operator.
+   * </ul>
+   *
    * @param target the collection that may contain the function input
    */
   @SuppressWarnings("NoHardKeywords") // We're stuck with the name for compatibility reasons.

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

@@ -208,6 +208,19 @@ public static Predicate<Class<?>> subtypeOf(Class<?> clazz) {
    * helps prevent bugs. This approach doesn't block any potential users since it is always possible
    * to use {@code Predicates.<Object>in()}.
    *
+   * <p>You may prefer to use a method reference (e.g., {@code target::contains}) instead of this
+   * method. However, there are some subtle considerations:
+   *
+   * <ul>
+   *   <li>The {@link Predicate} returned by this method is {@link Serializable}.
+   *   <li>The {@link Predicate} returned by this method catches {@link ClassCastException} and
+   *       {@link NullPointerException}.
+   *   <li>Code that chains multiple predicates together (especially negations) may be more readable
+   *       using this method. For example, {@code not(in(target))} is generally more readable than
+   *       {@code not(target::contains)}.
+   *   <li>This method's name conflicts with Kotlin's {@code in} operator.
+   * </ul>
+   *
    * @param target the collection that may contain the function input
    */
   @SuppressWarnings("NoHardKeywords") // We're stuck with the name for compatibility reasons.