Update the docs for FLAG_UPDATE_CURRENT and FLAG_IMMUTABLE

to add how they interact with each other. This seems to be a common
confusion for users. This change adds more context around what the two
flags mean in terms of allowing changes to a PendingIntent and that it
should be fine to use both together.

Bug: 160794467
Test: Green builds
Change-Id: I66f3744ca95252bdfebf8c9711eec7e8bfd059c8

core/java/android/app/PendingIntent.java

@@ -179,6 +179,12 @@ public final class PendingIntent implements Parcelable {
      * extras change, and don't care that any entities that received your
      * previous PendingIntent will be able to launch it with your new
      * extras even if they are not explicitly given to it.
+     *
+     * <p>{@link #FLAG_UPDATE_CURRENT} still works even if {@link
+     * #FLAG_IMMUTABLE} is set - the creator of the PendingIntent can always
+     * update the PendingIntent itself. The IMMUTABLE flag only limits the
+     * ability to alter the semantics of the intent that is sent by {@link
+     * #send} by the invoker of {@link #send}.
      */
     public static final int FLAG_UPDATE_CURRENT = 1<<27;
 
@@ -187,6 +193,11 @@ public final class PendingIntent implements Parcelable {
      * This means that the additional intent argument passed to the send
      * methods to fill in unpopulated properties of this intent will be
      * ignored.
+     *
+     * <p>{@link #FLAG_IMMUTABLE} only limits the ability to alter the
+     * semantics of the intent that is sent by {@link #send} by the invoker of
+     * {@link #send}. The creator of the PendingIntent can always update the
+     * PendingIntent itself via {@link #FLAG_UPDATE_CURRENT}.
      */
     public static final int FLAG_IMMUTABLE = 1<<26;