DO NOT MERGE Cherry-pick: Doc fixes for Notification.WearableExtender

Change-Id: I22947e30d329e667079555ac4ac5f9b25d6bd3fa

1 files changed, 44 insertions, 19 deletions

diff --git a/core/java/android/app/Notification.java b/core/java/android/app/Notification.java
index 6e23b11..70f270f 100644
--- a/core/java/android/app/Notification.java
+++ b/core/java/android/app/Notification.java
@@ -989,10 +989,9 @@ public class Notification implements Parcelable
          * <pre class="prettyprint">
          * Notification.Action action = new Notification.Action.Builder(
          *         R.drawable.archive_all, "Archive all", actionIntent)
-         *         .apply(new Notification.Action.WearableExtender()
+         *         .extend(new Notification.Action.WearableExtender()
          *                 .setAvailableOffline(false))
-         *         .build();
-         * </pre>
+         *         .build();</pre>
          */
         public static final class WearableExtender implements Extender {
             /** Notification action extra which contains wearable extensions */
@@ -3307,8 +3306,7 @@ public class Notification implements Parcelable
      * <pre class="prettyprint">
      * Notification.WearableExtender wearableExtender = new Notification.WearableExtender(
      *         notification);
-     * List&lt;Notification&gt; pages = wearableExtender.getPages();
-     * </pre>
+     * List&lt;Notification&gt; pages = wearableExtender.getPages();</pre>
      */
     public static final class WearableExtender implements Extender {
         /**
@@ -3553,7 +3551,27 @@ public class Notification implements Parcelable
 
         /**
          * Set an intent to launch inside of an activity view when displaying
-         * this notification. This {@link PendingIntent} should be for an activity.
+         * this notification. The {@link PendingIntent} provided should be for an activity.
+         *
+         * <pre class="prettyprint">
+         * Intent displayIntent = new Intent(context, MyDisplayActivity.class);
+         * PendingIntent displayPendingIntent = PendingIntent.getActivity(context,
+         *         0, displayIntent, PendingIntent.FLAG_UPDATE_CURRENT);
+         * Notification notif = new Notification.Builder(context)
+         *         .extend(new Notification.WearableExtender()
+         *                 .setDisplayIntent(displayPendingIntent)
+         *                 .setCustomSizePreset(Notification.WearableExtender.SIZE_MEDIUM))
+         *         .build();</pre>
+         *
+         * <p>The activity to launch needs to allow embedding, must be exported, and
+         * should have an empty task affinity.
+         *
+         * <p>Example AndroidManifest.xml entry:
+         * <pre class="prettyprint">
+         * &lt;activity android:name=&quot;com.example.MyDisplayActivity&quot;
+         *     android:exported=&quot;true&quot;
+         *     android:allowEmbedded=&quot;true&quot;
+         *     android:taskAffinity=&quot;&quot; /&gt;</pre>
          *
          * @param intent the {@link PendingIntent} for an activity
          * @return this object for method chaining
@@ -3687,12 +3705,17 @@ public class Notification implements Parcelable
 
         /**
          * Set an action from this notification's actions to be clickable with the content of
-         * this notification page. This action will no longer display separately from the
-         * notification content. This action's icon will display with optional subtext provided
-         * by the action's title.
-         * @param actionIndex The index of the action to hoist on the current notification page.
-         *                    If wearable actions are present, this index will apply to that list,
-         *                    otherwise it will apply to the main notification's actions list.
+         * this notification. This action will no longer display separately from the
+         * notification's content.
+         *
+         * <p>For notifications with multiple pages, child pages can also have content action's
+         * set, although the list of available actions comes from the main notification and not
+         * from the child page's notification.
+         *
+         * @param actionIndex The index of the action to hoist onto the current notification page.
+         *                    If wearable actions were added to the main notification, this index
+         *                    will apply to that list, otherwise it will apply to the regular
+         *                    actions list.
          */
         public WearableExtender setContentAction(int actionIndex) {
             mContentActionIndex = actionIndex;
@@ -3700,14 +3723,16 @@ public class Notification implements Parcelable
         }
 
         /**
-         * Get the action index of an action from this notification to show as clickable with
-         * the content of this notification page. When the user clicks this notification page,
-         * this action will trigger. This action will no longer display separately from the
-         * notification content. The action's icon will display with optional subtext provided
-         * by the action's title.
+         * Get the action index from this notification's actions to be clickable with the
+         * content of this notification. This action will no longer display separately
+         * from the notification's content.
+         *
+         * <p>For notifications with multiple pages, child pages can also have content action's
+         * set, although the list of available actions comes from the main notification and not
+         * from the child page's notification.
          *
-         * <p>If wearable specific actions are present, this index will apply to that list,
-         * otherwise it will apply to the main notification's actions list.
+         * <p>If wearable specific actions were added to the main notification, this index will
+         * apply to that list, otherwise it will apply to the regular actions list.
          */
         public int getContentAction() {
             return mContentActionIndex;