[TextInputLayout] Updated documentation to clarify end icon mode's ex…

…pected usage and behaviors relating to the icon's drawable.

Resolves #2528

PiperOrigin-RevId: 427506995

docs/components/TextField.md

@@ -194,6 +194,13 @@ textField.addOnEndIconChangedListener {
 end/right compound `Drawable` on the `TextInputEditText`. The same applies to
 the now-deprecated `passwordToggle*` attributes.
 
+**Important:** Calling `setEndIconMode` will initialize the icon with its
+default features, such as default drawables, and in the case of the custom mode,
+an empty drawable. You can add customizations after calling `setEndIconMode`.
+The exception for this is if a drawable was specified in XML via the
+`app:endIconDrawable` attribute. An end icon drawable set in XML will take
+precedence and override an existing default icon.
+
 See the full list of
 [end icon modes](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/textfield/res/values/attrs.xml#L149).
 

lib/java/com/google/android/material/textfield/CustomEndIconDelegate.java

@@ -21,6 +21,11 @@
 
 /**
  * Default initialization of a custom {@link TextInputLayout.EndIconMode}.
+ *
+ * <p>It will initialize with an empty icon drawable unless one was specified in xml via the {@code
+ * app:endIconDrawable} attribute. You can also specify the drawable by calling {@link
+ * TextInputLayout#setEndIconDrawable(int)} after calling {@link
+ * TextInputLayout#setEndIconMode(int)}.
  */
 class CustomEndIconDelegate extends EndIconDelegate {
 

lib/java/com/google/android/material/textfield/TextInputLayout.java

@@ -3606,7 +3606,8 @@ public boolean isEndIconCheckable() {
   }
 
   /**
-   * Set the icon to use for the end icon.
+   * Set the icon to use for the end icon. This method should be called after specifying an {@link
+   * TextInputLayout.EndIconMode} via {@link #setEndIconMode(int)}.
    *
    * <p>If you use an icon you should also set a description for its action using {@link
    * #setEndIconContentDescription(CharSequence)}. This is used for accessibility.
@@ -3619,7 +3620,8 @@ public void setEndIconDrawable(@DrawableRes int resId) {
   }
 
   /**
-   * Set the icon to use for the end icon.
+   * Set the icon to use for the end icon. This method should be called after specifying an {@link
+   * TextInputLayout.EndIconMode} via {@link #setEndIconMode(int)}.
    *
    * <p>If you use an icon you should also set a description for its action using {@link
    * #setEndIconContentDescription(CharSequence)}. This is used for accessibility.