Merge "ShortcutManager javadoc" into nyc-mr1-dev

3 files changed, 493 insertions, 137 deletions

diff --git a/core/java/android/content/pm/LauncherApps.java b/core/java/android/content/pm/LauncherApps.java
index 528fe2002391..2133222c7f54 100644
--- a/core/java/android/content/pm/LauncherApps.java
+++ b/core/java/android/content/pm/LauncherApps.java
@@ -164,17 +164,19 @@ public class LauncherApps {
         }
 
         /**
-         * Indicates that one or more shortcuts (which may be dynamic and/or pinned)
+         * Indicates that one or more shortcuts of any kinds (dynamic, pinned, or manifest)
          * have been added, updated or removed.
          *
          * <p>Only the applications that are allowed to access the shortcut information,
          * as defined in {@link #hasShortcutHostPermission()}, will receive it.
          *
          * @param packageName The name of the package that has the shortcuts.
-         * @param shortcuts all shortcuts from the package (dynamic, manifest and/or pinned).
-         *    Only "key" information will be provided, as defined in
+         * @param shortcuts all shortcuts from the package (dynamic, manifest and/or pinned) will
+         *    be passed. Only "key" information will be provided, as defined in
          *    {@link ShortcutInfo#hasKeyFieldsOnly()}.
          * @param user The UserHandle of the profile that generated the change.
+         *
+         * @see ShortcutManager
          */
         public void onShortcutsChanged(@NonNull String packageName,
                 @NonNull List<ShortcutInfo> shortcuts, @NonNull UserHandle user) {
@@ -222,7 +224,17 @@ public class LauncherApps {
 
         /**
          * Requests "key" fields only.  See {@link ShortcutInfo#hasKeyFieldsOnly()} for which
-         * fields are available.
+         * fields are available.  This allows quicker access to shortcut information in order to
+         * determine in-memory cache in the caller needs to be updated.
+         *
+         * <p>Typically, launcher applications cache all or most shortcuts' information
+         * in memory in order to show shortcuts without a delay.  When they want to update their
+         * cache (e.g. when their process restart), they can fetch all shortcuts' information with
+         * with this flag, then check {@link ShortcutInfo#getLastChangedTimestamp()} for each
+         * shortcut and issue a second call to fetch the non-key information of only updated
+         * shortcuts.
+         *
+         * @see ShortcutManager
          */
         public static final int FLAG_GET_KEY_FIELDS_ONLY = 1 << 2;
 
@@ -255,8 +267,8 @@ public class LauncherApps {
         }
 
         /**
-         * If non-zero, returns only shortcuts that have been added or updated since the timestamp,
-         * which is a milliseconds since the Epoch.
+         * If non-zero, returns only shortcuts that have been added or updated since the timestamp.
+         * Units are as per {@link System#currentTimeMillis()}.
          */
         public ShortcutQuery setChangedSince(long changedSince) {
             mChangedSince = changedSince;
@@ -273,7 +285,7 @@ public class LauncherApps {
 
         /**
          * If non-null, return only the specified shortcuts by ID.  When setting this field,
-         * a packange name must also be set with {@link #setPackage}.
+         * a package name must also be set with {@link #setPackage}.
          */
         public ShortcutQuery setShortcutIds(@Nullable List<String> shortcutIds) {
             mShortcutIds = shortcutIds;
@@ -291,7 +303,13 @@ public class LauncherApps {
         }
 
         /**
-         * Set query options.
+         * Set query options.  At least one of the {@code MATCH} flags should be set.  (Otherwise
+         * no shortcuts will be returned.)
+         *
+         * @see {@link #FLAG_MATCH_DYNAMIC}
+         * @see {@link #FLAG_MATCH_PINNED}
+         * @see {@link #FLAG_MATCH_MANIFEST}
+         * @see {@link #FLAG_GET_KEY_FIELDS_ONLY}
          */
         public ShortcutQuery setQueryFlags(@QueryFlags int queryFlags) {
             mQueryFlags = queryFlags;
@@ -460,10 +478,14 @@ public class LauncherApps {
      *
      * <p>Only the default launcher can access the shortcut information.
      *
-     * <p>Note when this method returns {@code false}, that may be a temporary situation because
+     * <p>Note when this method returns {@code false}, it may be a temporary situation because
      * the user is trying a new launcher application.  The user may decide to change the default
-     * launcher to the calling application again, so even if a launcher application loses
+     * launcher back to the calling application again, so even if a launcher application loses
      * this permission, it does <b>not</b> have to purge pinned shortcut information.
+     * Also in this situation, pinned shortcuts can still be started, even though the caller
+     * no longer has the shortcut host permission.
+     *
+     * @see ShortcutManager
      */
     public boolean hasShortcutHostPermission() {
         try {
@@ -474,7 +496,7 @@ public class LauncherApps {
     }
 
     /**
-     * Returns the IDs of {@link ShortcutInfo}s that match {@code query}.
+     * Returns {@link ShortcutInfo}s that match {@code query}.
      *
      * <p>Callers must be allowed to access the shortcut information, as defined in {@link
      * #hasShortcutHostPermission()}.
@@ -483,6 +505,8 @@ public class LauncherApps {
      * @param user The UserHandle of the profile.
      *
      * @return the IDs of {@link ShortcutInfo}s that match the query.
+     *
+     * @see ShortcutManager
      */
     @Nullable
     public List<ShortcutInfo> getShortcuts(@NonNull ShortcutQuery query,
@@ -523,6 +547,8 @@ public class LauncherApps {
      * @param packageName The target package name.
      * @param shortcutIds The IDs of the shortcut to be pinned.
      * @param user The UserHandle of the profile.
+     *
+     * @see ShortcutManager
      */
     public void pinShortcuts(@NonNull String packageName, @NonNull List<String> shortcutIds,
             @NonNull UserHandle user) {
@@ -586,11 +612,17 @@ public class LauncherApps {
     /**
      * Returns the icon for this shortcut, without any badging for the profile.
      *
+     * <p>Callers must be allowed to access the shortcut information, as defined in {@link
+     * #hasShortcutHostPermission()}.
+     *
      * @param density The preferred density of the icon, zero for default density. Use
      * density DPI values from {@link DisplayMetrics}.
+     *
+     * @return The drawable associated with the shortcut.
+     *
+     * @see ShortcutManager
      * @see #getShortcutBadgedIconDrawable(ShortcutInfo, int)
      * @see DisplayMetrics
-     * @return The drawable associated with the shortcut.
      */
     public Drawable getShortcutIconDrawable(@NonNull ShortcutInfo shortcut, int density) {
         if (shortcut.hasIconFile()) {
@@ -628,10 +660,15 @@ public class LauncherApps {
     /**
      * Returns the shortcut icon with badging appropriate for the profile.
      *
+     * <p>Callers must be allowed to access the shortcut information, as defined in {@link
+     * #hasShortcutHostPermission()}.
+     *
      * @param density Optional density for the icon, or 0 to use the default density. Use
-     * {@link DisplayMetrics} for DPI values.
-     * @see DisplayMetrics
      * @return A badged icon for the shortcut.
+     *
+     * @see ShortcutManager
+     * @see #getShortcutBadgedIconDrawable(ShortcutInfo, int)
+     * @see DisplayMetrics
      */
     public Drawable getShortcutBadgedIconDrawable(ShortcutInfo shortcut, int density) {
         final Drawable originalIcon = getShortcutIconDrawable(shortcut, density);
@@ -641,7 +678,7 @@ public class LauncherApps {
     }
 
     /**
-     * Launches a shortcut.
+     * Starts a shortcut.
      *
      * <p>Callers must be allowed to access the shortcut information, as defined in {@link
      * #hasShortcutHostPermission()}.
diff --git a/core/java/android/content/pm/ShortcutInfo.java b/core/java/android/content/pm/ShortcutInfo.java
index 39e15e01bab4..8ea77d6428a8 100644
--- a/core/java/android/content/pm/ShortcutInfo.java
+++ b/core/java/android/content/pm/ShortcutInfo.java
@@ -22,8 +22,10 @@ import android.annotation.UserIdInt;
 import android.content.ComponentName;
 import android.content.Context;
 import android.content.Intent;
+import android.content.pm.LauncherApps.ShortcutQuery;
 import android.content.res.Resources;
 import android.content.res.Resources.NotFoundException;
+import android.graphics.Bitmap;
 import android.graphics.drawable.Icon;
 import android.os.Bundle;
 import android.os.Parcel;
@@ -42,20 +44,10 @@ import java.lang.annotation.RetentionPolicy;
 import java.util.List;
 import java.util.Set;
 
-// TODO Enhance javadoc
 /**
+ * Represents a "launcher shortcut" that can be published via {@link ShortcutManager}.
  *
- * Represents a shortcut from an application.
- *
- * <p>Notes about icons:
- * <ul>
- *     <li>If an {@link Icon} is a resource, the system keeps the package name and the resource ID.
- *     Otherwise, the bitmap is fetched when it's registered to ShortcutManager,
- *     then shrunk if necessary, and persisted.
- *     <li>The system disallows byte[] icons, because they can easily go over the binder size limit.
- * </ul>
- *
- * @see {@link ShortcutManager}.
+ * @see ShortcutManager
  */
 public final class ShortcutInfo implements Parcelable {
     static final String TAG = "Shortcut";
@@ -149,7 +141,7 @@ public final class ShortcutInfo implements Parcelable {
     public @interface CloneFlags {}
 
     /**
-     * Shortcut category for
+     * Shortcut category for messaging related actions, such as chat.
      */
     public static final String SHORTCUT_CATEGORY_CONVERSATION = "android.shortcut.conversation";
 
@@ -665,6 +657,8 @@ public final class ShortcutInfo implements Parcelable {
 
     /**
      * Builder class for {@link ShortcutInfo} objects.
+     *
+     * @see ShortcutManager
      */
     public static class Builder {
         private final Context mContext;
@@ -727,19 +721,25 @@ public final class ShortcutInfo implements Parcelable {
         }
 
         /**
-         * Sets the target activity. A shortcut will be shown with this activity on the launcher.
+         * Sets the target activity.  A shortcut will be shown along with this activity's icon
+         * on the launcher.
          *
-         * <p>Only "main" activities -- i.e. ones with an intent filter for
-         * {@link Intent#ACTION_MAIN} and {@link Intent#CATEGORY_LAUNCHER} can be target activities.
+         * <p>This is a mandatory field when publishing a new shortcut with
+         * {@link ShortcutManager#addDynamicShortcuts(List)} or
+         * {@link ShortcutManager#setDynamicShortcuts(List)}.
+         *
+         * <ul>
+         * <li>Only "main" activities (ones with an intent filter for
+         * {@link Intent#ACTION_MAIN} and {@link Intent#CATEGORY_LAUNCHER}) can be target
+         * activities.
          *
-         * <p>By default, the first main activity defined in the application manifest will be
+         * <li>By default, the first main activity defined in the application manifest will be
          * the target.
          *
-         * <p>The package name of the target activity must match the package name of the shortcut
-         * publisher.
+         * <li>A target activity must belong to the publisher application.
+         * </ul>
          *
-         * <p>This has nothing to do with the activity that this shortcut will launch.  This is
-         * a hint to the launcher app about which launcher icon to associate this shortcut with.
+         * @see ShortcutInfo#getActivity()
          */
         @NonNull
         public Builder setActivity(@NonNull ComponentName activity) {
@@ -748,18 +748,23 @@ public final class ShortcutInfo implements Parcelable {
         }
 
         /**
-         * Sets an icon.
-         *
-         * <ul>
-         *     <li>Tints set by {@link Icon#setTint} or {@link Icon#setTintList} are not supported.
-         *     <li>Bitmaps and resources are supported, but "content:" URIs are not supported.
-         * </ul>
+         * Sets an icon of a shortcut.
          *
-         * <p>For performance and security reasons, icons will <b>NOT</b> be available on instances
-         * returned by {@link ShortcutManager} or {@link LauncherApps}.  Default launcher application
-         * can use {@link LauncherApps#getShortcutIconDrawable(ShortcutInfo, int)}
+         * <p>Icons are not available on {@link ShortcutInfo} instances
+         * returned by {@link ShortcutManager} or {@link LauncherApps}.  The default launcher
+         * application can use {@link LauncherApps#getShortcutIconDrawable(ShortcutInfo, int)}
          * or {@link LauncherApps#getShortcutBadgedIconDrawable(ShortcutInfo, int)} to fetch
          * shortcut icons.
+         *
+         * <p>Tints set with {@link Icon#setTint} or {@link Icon#setTintList} are not supported
+         * and will be ignored.
+         *
+         * <p>Only icons created with {@link Icon#createWithBitmap(Bitmap)} and
+         * {@link Icon#createWithResource} are supported.  Other types such as URI based icons
+         * are not supported.
+         *
+         * @see LauncherApps#getShortcutIconDrawable(ShortcutInfo, int)
+         * @see LauncherApps#getShortcutBadgedIconDrawable(ShortcutInfo, int)
          */
         @NonNull
         public Builder setIcon(Icon icon) {
@@ -781,11 +786,15 @@ public final class ShortcutInfo implements Parcelable {
         /**
          * Sets the short title of a shortcut.
          *
-         * <p>This is a mandatory field, unless it's passed to
-         * {@link ShortcutManager#updateShortcuts(List)}.
+         * <p>This is a mandatory field when publishing a new shortcut with
+         * {@link ShortcutManager#addDynamicShortcuts(List)} or
+         * {@link ShortcutManager#setDynamicShortcuts(List)}.
+         *
+         * <p>This field is intended for a concise description of a shortcut.
+         *
+         * <p>The recommended max length is 10 characters.
          *
-         * <p>This field is intended for a concise description of a shortcut displayed under
-         * an icon.  The recommend max length is 10 characters.
+         * @see ShortcutInfo#getShortLabel()
          */
         @NonNull
         public Builder setShortLabel(@NonNull CharSequence shortLabel) {
@@ -809,8 +818,11 @@ public final class ShortcutInfo implements Parcelable {
          * Sets the text of a shortcut.
          *
          * <p>This field is intended to be more descriptive than the shortcut title.  The launcher
-         * shows this instead of the short title, when it has enough space.
-         * The recommend max length is 25 characters.
+         * shows this instead of the short title when it has enough space.
+         *
+         * <p>The recommend max length is 25 characters.
+         *
+         * @see ShortcutInfo#getLongLabel()
          */
         @NonNull
         public Builder setLongLabel(@NonNull CharSequence longLabel) {
@@ -854,6 +866,11 @@ public final class ShortcutInfo implements Parcelable {
             return this;
         }
 
+        /**
+         * Sets the message that should be shown when a shortcut is launched when disabled.
+         *
+         * @see ShortcutInfo#getDisabledMessage()
+         */
         @NonNull
         public Builder setDisabledMessage(@NonNull CharSequence disabledMessage) {
             Preconditions.checkState(
@@ -869,6 +886,7 @@ public final class ShortcutInfo implements Parcelable {
          * categorise shortcuts.
          *
          * @see #SHORTCUT_CATEGORY_CONVERSATION
+         * @see ShortcutInfo#getCategories()
          */
         @NonNull
         public Builder setCategories(Set<String> categories) {
@@ -877,8 +895,22 @@ public final class ShortcutInfo implements Parcelable {
         }
 
         /**
-         * Sets the intent of a shortcut.  This is a mandatory field.  The extras must only contain
-         * persistable information.  (See {@link PersistableBundle}).
+         * Sets the intent of a shortcut.
+         *
+         * <p>This is a mandatory field when publishing a new shortcut with
+         * {@link ShortcutManager#addDynamicShortcuts(List)} or
+         * {@link ShortcutManager#setDynamicShortcuts(List)}.
+         *
+         * <p>A shortcut can launch any intent that the publisher application has a permission to
+         * launch -- for example, a shortcut can launch an unexported activity within the publisher
+         * application.
+         *
+         * <p>A shortcut intent doesn't have to point at the target activity.
+         *
+         * <p>{@code intent} can contain extras, but only values of the primitive types are
+         * supported so the system can persist them.
+         *
+         * @see ShortcutInfo#getIntent()
          */
         @NonNull
         public Builder setIntent(@NonNull Intent intent) {
@@ -890,6 +922,8 @@ public final class ShortcutInfo implements Parcelable {
         /**
          * "Rank" of a shortcut, which is a non-negative value that's used by the launcher app
          * to sort shortcuts.
+         *
+         * See {@link ShortcutInfo#getRank()} for details.
          */
         @NonNull
         public Builder setRank(int rank) {
@@ -903,7 +937,7 @@ public final class ShortcutInfo implements Parcelable {
          * Extras that application can set to any purposes.
          *
          * <p>Applications can store any meta-data of
-         * shortcuts in this, and retrieve later from {@link ShortcutInfo#getExtras()}.
+         * shortcuts in extras, and retrieve later from {@link ShortcutInfo#getExtras()}.
          */
         @NonNull
         public Builder setExtras(@NonNull PersistableBundle extras) {
@@ -921,7 +955,11 @@ public final class ShortcutInfo implements Parcelable {
     }
 
     /**
-     * Return the ID of the shortcut.
+     * Returns the ID of a shortcut.
+     *
+     * <p>Shortcut IDs are unique within each publisher application, and must be stable across
+     * devices to that shortcuts will still be valid when restored.  See {@link ShortcutManager}
+     * for details.
      */
     @NonNull
     public String getId() {
@@ -929,7 +967,7 @@ public final class ShortcutInfo implements Parcelable {
     }
 
     /**
-     * Return the package name of the creator application.
+     * Return the package name of the publisher application.
      */
     @NonNull
     public String getPackage() {
@@ -937,11 +975,10 @@ public final class ShortcutInfo implements Parcelable {
     }
 
     /**
-     * Return the target activity, which may be null, in which case the shortcut is not associated
-     * with a specific activity.
+     * Return the target activity.
      *
-     * <p>This has nothing to do with the activity that this shortcut will launch.  This is
-     * a hint to the launcher app that on which launcher icon this shortcut should be shown.
+     * <p>This has nothing to do with the activity that this shortcut will launch.  Launcher
+     * applications should show a shortcut along with the launcher icon for this activity.
      *
      * @see Builder#setActivity
      */
@@ -956,11 +993,7 @@ public final class ShortcutInfo implements Parcelable {
     }
 
     /**
-     * Icon.
-     *
-     * For performance reasons, this will <b>NOT</b> be available when an instance is returned
-     * by {@link ShortcutManager} or {@link LauncherApps}.  A launcher application needs to use
-     * other APIs in LauncherApps to fetch the bitmap.
+     * Returns the shortcut icon.
      *
      * @hide
      */
@@ -996,10 +1029,9 @@ public final class ShortcutInfo implements Parcelable {
     }
 
     /**
-     * Return the shorter version of the shortcut title.
+     * Return the shorter description of a shortcut.
      *
-     * <p>All shortcuts must have a non-empty title, but this method will return null when
-     * {@link #hasKeyFieldsOnly()} is true.
+     * @see Builder#setShortLabel(CharSequence)
      */
     @Nullable
     public CharSequence getShortLabel() {
@@ -1012,7 +1044,9 @@ public final class ShortcutInfo implements Parcelable {
     }
 
     /**
-     * Return the shortcut text.
+     * Return the longer description of a shortcut.
+     *
+     * @see Builder#setLongLabel(CharSequence)
      */
     @Nullable
     public CharSequence getLongLabel() {
@@ -1026,6 +1060,8 @@ public final class ShortcutInfo implements Parcelable {
 
     /**
      * Return the message that should be shown when a shortcut in disabled state is launched.
+     *
+     * @see Builder#setDisabledMessage(CharSequence)
      */
     @Nullable
     public CharSequence getDisabledMessage() {
@@ -1039,6 +1075,8 @@ public final class ShortcutInfo implements Parcelable {
 
     /**
      * Return the categories.
+     *
+     * @see Builder#setCategories(Set)
      */
     @Nullable
     public Set<String> getCategories() {
@@ -1048,12 +1086,11 @@ public final class ShortcutInfo implements Parcelable {
     /**
      * Return the intent.
      *
-     * <p>All shortcuts must have an intent, but this method will return null when
-     * {@link #hasKeyFieldsOnly()} is true.
+     * <p>Launcher applications <b>cannot</b> see the intent.  If a {@link ShortcutInfo} is
+     * obtained via {@link LauncherApps}, then this method will always return null.
+     * Launchers can only start a shortcut intent with {@link LauncherApps#startShortcut}.
      *
-     * <p>Launcher apps <b>cannot</b> see the intent.  If a {@link ShortcutInfo} is obtained via
-     * {@link LauncherApps}, then this method will always return null.  Launcher apps can only
-     * start a shortcut intent with {@link LauncherApps#startShortcut}.
+     * @see Builder#setIntent(Intent)
      */
     @Nullable
     public Intent getIntent() {
@@ -1096,6 +1133,10 @@ public final class ShortcutInfo implements Parcelable {
      *
      * <p>"Floating" shortcuts (i.e. shortcuts that are neither dynamic nor manifest) will all
      * have rank 0, because there's no sorting for them.
+     *
+     * See the {@link ShortcutManager}'s class javadoc for details.
+     *
+     * @see Builder#setRank(int)
      */
     public int getRank() {
         return mRank;
@@ -1139,6 +1180,8 @@ public final class ShortcutInfo implements Parcelable {
 
     /**
      * Extras that application can set to any purposes.
+     *
+     * @see Builder#setExtras(PersistableBundle)
      */
     @Nullable
     public PersistableBundle getExtras() {
@@ -1151,7 +1194,7 @@ public final class ShortcutInfo implements Parcelable {
     }
 
     /**
-     * {@link UserHandle} on which the publisher created shortcuts.
+     * {@link UserHandle} on which the publisher created a shortcut.
      */
     public UserHandle getUserHandle() {
         return UserHandle.of(mUserId);
@@ -1201,16 +1244,13 @@ public final class ShortcutInfo implements Parcelable {
     }
 
     /**
-     * Return whether a shortcut is published via AndroidManifest.xml or not.  If {@code true},
+     * Return whether a shortcut is published AndroidManifest.xml or not.  If {@code true},
      * it's also {@link #isImmutable()}.
      *
      * <p>When an app is upgraded and a shortcut is no longer published from AndroidManifest.xml,
      * this will be set to {@code false}.  If the shortcut is not pinned, then it'll just disappear.
      * However, if it's pinned, it will still be alive, and {@link #isEnabled()} will be
      * {@code false} and {@link #isImmutable()} will be {@code true}.
-     *
-     * <p>NOTE this is whether a shortcut is published from the <b>current version's</b>
-     * AndroidManifest.xml.
      */
     public boolean isDeclaredInManifest() {
         return hasFlags(FLAG_MANIFEST);
@@ -1311,6 +1351,12 @@ public final class ShortcutInfo implements Parcelable {
      *     <li>{@link #isEnabled()}
      *     <li>{@link #getUserHandle()}
      * </ul>
+     *
+     * <p>{@link ShortcutInfo}s passed to
+     * {@link LauncherApps.Callback#onShortcutsChanged(String, List, UserHandle)}
+     * as well as returned by {@link LauncherApps#getShortcuts(ShortcutQuery, UserHandle)} with
+     * the {@link ShortcutQuery#FLAG_GET_KEY_FIELDS_ONLY} option will only have key information
+     * for performance reasons.
      */
     public boolean hasKeyFieldsOnly() {
         return hasFlags(FLAG_KEY_FIELDS_ONLY);
diff --git a/core/java/android/content/pm/ShortcutManager.java b/core/java/android/content/pm/ShortcutManager.java
index 1af63a01ce2b..f6c0be07db84 100644
--- a/core/java/android/content/pm/ShortcutManager.java
+++ b/core/java/android/content/pm/ShortcutManager.java
@@ -20,6 +20,7 @@ import android.annotation.TestApi;
 import android.annotation.UserIdInt;
 import android.app.usage.UsageStatsManager;
 import android.content.Context;
+import android.content.Intent;
 import android.os.RemoteException;
 import android.os.ServiceManager;
 import android.os.UserHandle;
@@ -28,62 +29,333 @@ import com.android.internal.annotations.VisibleForTesting;
 
 import java.util.List;
 
-// TODO Enhance javadoc
 /**
- * <b>TODO: Update to reflect DR changes, such as manifest shortcuts.</b><br>
+ * ShortcutManager manages "launcher shortcuts" (or simply "shortcuts").  Shortcuts provide user
+ * with quick
+ * ways to access activities other than the main activity from the launcher to users.  For example,
+ * an email application may publish the "compose new email" action which will directly open the
+ * compose activity.  The {@link ShortcutInfo} class represents shortcuts.
  *
- * {@link ShortcutManager} manages shortcuts created by applications.
+ * <h3>Dynamic Shortcuts and Manifest Shortcuts</h3>
  *
- * <h3>Dynamic shortcuts and pinned shortcuts</h3>
+ * There are two ways to publish shortcuts: manifest shortcuts and dynamic shortcuts.
  *
- * An application can publish shortcuts with {@link #setDynamicShortcuts(List)} and
- * {@link #addDynamicShortcuts(List)}.  There can be at most
- * {@link #getMaxShortcutCountPerActivity()} number of dynamic shortcuts at a time from the
- * same application.
- * A dynamic shortcut can be deleted with {@link #removeDynamicShortcuts(List)}, and apps
- * can also use {@link #removeAllDynamicShortcuts()} to delete all dynamic shortcuts.
+ * <ul>
+ * <li>Manifest shortcuts are declared in a resource XML which is referred to from
+ * AndroidManifest.xml.  Manifest shortcuts are published when an application is installed,
+ * and are updated when an application is upgraded with an updated XML file.
+ * Manifest shortcuts are immutable and their
+ * definitions (e.g. icons and labels) can not be changed dynamically (without upgrading the
+ * publisher application).
+ *
+ * <li>Dynamic shortcuts are published at runtime with {@link ShortcutManager} APIs.
+ * Applications can publish, update and remove dynamic shortcuts at runtime with certain limitations
+ * described below.
+ * </ul>
+ *
+ * <p>Only "main" activities (i.e. activities that handle the {@code MAIN} action and the
+ * {@code LAUNCHER} category) can have shortcuts.  If an application has multiple main activities,
+ * they will have different set of shortcuts.
+ *
+ * <p>Dynamic shortcuts and manifest shortcuts are shown by launcher applications when the user
+ * takes a certain action (e.g. long-press) on an application launcher icon.
+ *
+ * <p>Each launcher icon can have at most {@link #getMaxShortcutCountPerActivity()} number of
+ * dynamic and manifest shortcuts combined.
+ *
+ *
+ * <h3>Pinning Shortcuts</h3>
+ *
+ * Launcher applications allow users to "pin" shortcuts so they're easier to access.  Both manifest
+ * and dynamic shortcuts can be pinned, to avoid user's confusion.
+ * Pinned shortcuts <b>cannot</b> be removed by publisher
+ * applications -- they are only removed when the publisher is uninstalled. (Or the user performs
+ * "clear data" on the publisher application on the Settings application.)
+ *
+ * <p>Publisher can however "disable" pinned shortcuts so they cannot be launched.  See below
+ * for details.
+ *
+ *
+ * <h3>Updating and Disabling Shortcuts</h3>
+ *
+ * <p>When a dynamic shortcut is pinned, even when the publisher removes it as a dynamic shortcut,
+ * the pinned shortcut will still be available and launchable.  This allows an application to have
+ * more than {@link #getMaxShortcutCountPerActivity()} number of shortcuts -- for example, suppose
+ * {@link #getMaxShortcutCountPerActivity()} is 5:
+ * <ul>
+ *     <li>A chat application publishes 5 dynamic shortcuts for the 5 most recent
+ *     conversations, "c1" - "c5".
+ *
+ *     <li>The user pins all of the 5 shortcuts.
+ *
+ *     <li>Later, the user has 3 newer conversations ("c6", "c7" and "c8"), so the application
+ *     re-publishes dynamic shortcuts and now it has the dynamic shortcuts "c4", "c5", "c6", "c7"
+ *     and "c8".  The publisher has to remove "c1", "c2" and "c3" because it can't have more than
+ *     5 dynamic shortcuts.
+ *
+ *     <li>However, even though "c1", "c2" and "c3" are no longer dynamic shortcuts, the pinned
+ *     shortcuts for those conversations are still available and launchable.
+ *
+ *     <li>At this point, the application has 8 shortcuts in total, including the 3 pinned
+ *     shortcuts, even though it's allowed to have at most 5 dynamic shortcuts.
+ *
+ *     <li>The application can use {@link #updateShortcuts(List)} to update any of the existing
+ *     8 shortcuts, when, for example, the chat peers' icons have changed.
+ * </ul>
+ * {@link #addDynamicShortcuts(List)} and {@link #setDynamicShortcuts(List)} can also be used
+ * to update existing shortcuts with the same IDs, but they <b>cannot</b> be used for
+ * non-dynamic pinned shortcuts because these two APIs will always try to make the passed
+ * shortcuts dynamic.
+ *
+ *
+ * <h4>Disabling Manifest Shortcuts</h4>
+ * Sometimes pinned shortcuts become obsolete and may not be usable.  For example, a pinned shortcut
+ * to a group chat will be unusable when the group chat room is deleted.  In cases like this,
+ * applications should use {@link #disableShortcuts(List)}, which will remove the specified dynamic
+ * shortcuts and also make the pinned shortcuts un-launchable, if any.
+ * {@link #disableShortcuts(List, CharSequence)} can also be used to disable shortcuts with
+ * a custom error message that will be shown when the user starts the shortcut.
+ *
+ * <h4>Disabling Manifest Shortcuts</h4>
+ * When an application is upgraded and the new version no longer has a manifest shortcut that
+ * the previous version had, this shortcut will no longer be published as a manifest shortcut.
+ *
+ * <p>If the shortcut is pinned, then the pinned shortcut will remain on the launcher, but will be
+ * disabled.  Note in this case, the pinned shortcut is no longer a manifest shortcut, but is
+ * still <b>immutable</b> and cannot be updated with the {@link ShortcutManager} APIs.
+ *
+ *
+ * <h3>Publishing Dynamic Shortcuts</h3>
+ *
+ * Applications can publish dynamic shortcuts with {@link #setDynamicShortcuts(List)}
+ * or {@link #addDynamicShortcuts(List)}.  {@link #updateShortcuts(List)} can also be used to
+ * update existing (mutable) shortcuts.
+ * Use {@link #removeDynamicShortcuts(List)} or {@link #removeAllDynamicShortcuts()} to remove
+ * dynamic shortcuts.
+ *
+ * <p>Example:
+ * <pre>
+ * ShortcutManager shortcutManager = getSystemService(ShortcutManager.class);
+ *
+ * ShortcutInfo shortcut = new ShortcutInfo.Builder(this, "id1")
+ *     .setIntent(new Intent(Intent.ACTION_VIEW, Uri.parse("http://www.mysite.com/")))
+ *     .setShortLabel("Web site")
+ *     .setLongLabel("Open the web site")
+ *     .setIcon(Icon.createWithResource(context, R.drawable.icon_website))
+ *     .build();
  *
- * <p>The shortcuts that are currently published by the above APIs are called "dynamic", because
- * they can be removed by the creator application at any time.  The user may "pin" dynamic shortcuts
- * on Launcher to make "pinned" shortcuts.  Pinned shortcuts <b>cannot</b> be removed by the creator
- * app.  An application can obtain all pinned shortcuts from itself with
- * {@link #getPinnedShortcuts()}.  Applications should keep the pinned shortcut information
- * up-to-date using {@link #updateShortcuts(List)}.
+ * shortcutManager.setDynamicShortcuts(Arrays.asList(shortcut));
+ * </pre>
  *
- * <p>The number of pinned shortcuts does not affect the number of dynamic shortcuts that can be
- * published by an application at a time.
- * No matter how many pinned shortcuts that Launcher has for an application, the
- * application can still always publish {@link #getMaxShortcutCountPerActivity()} number of
- * dynamic
- * shortcuts.
  *
- * <h3>Shortcut IDs</h3>
+ * <h3>Publishing Manifest Shortcuts</h3>
  *
- * Each shortcut must have an ID, which must be unique within each application.  When a shortcut is
- * published, existing shortcuts with the same ID will be updated.  Note this may include a
- * pinned shortcut.
+ * In order to add manifest shortcuts to your application, first add
+ * {@code <meta-data android:name="android.app.shortcuts" />} to your main activity in
+ * AndroidManifest.xml.
+ * <pre>
+ * &lt;manifest xmlns:android=&quot;http://schemas.android.com/apk/res/android&quot;
+ *   package=&quot;com.example.myapplication&quot;&gt;
+ *   &lt;application . . .&gt;
+ *     &lt;activity android:name=&quot;Main&quot;&gt;
+ *       &lt;intent-filter&gt;
+ *         &lt;action android:name=&quot;android.intent.action.MAIN&quot; /&gt;
+ *         &lt;category android:name=&quot;android.intent.category.LAUNCHER&quot; /&gt;
+ *       &lt;/intent-filter&gt;
+ *       <b>&lt;meta-data android:name=&quot;android.app.shortcuts&quot; android:resource=&quot;@xml/shortcuts&quot;/&gt;</b>
+ *     &lt;/activity&gt;
+ *   &lt;/application&gt;
+ * &lt;/manifest&gt;
+ * </pre>
+ *
+ * Then define shortcuts in res/xml/shortcuts.xml.
+ * <pre>
+ * &lt;shortcuts xmlns:android=&quot;http://schemas.android.com/apk/res/android&quot; &gt;
+ *   &lt;shortcut
+ *     android:shortcutId=&quot;compose&quot;
+ *     android:enabled=&quot;true&quot;
+ *     android:icon=&quot;@drawable/compose_icon&quot;
+ *     android:shortcutShortLabel=&quot;@string/compose_shortcut_short_label1&quot;
+ *     android:shortcutLongLabel=&quot;@string/compose_shortcut_short_label1&quot;
+ *     android:shortcutDisabledMessage=&quot;@string/compose_disabled_message1&quot;
+ *     &gt;
+ *     &lt;intent
+ *       android:action=&quot;android.intent.action.VIEW&quot;
+ *       android:targetPackage=&quot;com.example.myapplication&quot;
+ *       android:targetClass=&quot;com.example.myapplication.ComposeActivity&quot; /&gt;
+ *     &lt;categories android:name=&quot;android.shortcut.conversation&quot; /&gt;
+ *   &lt;/shortcut&gt;
+ *   &lt;!-- more shortcut can go here --&gt;
+ * &lt;/shortcuts&gt;
+ * </pre>
+ * <ul>
+ *   <li>{@code android:shortcutId} Mandatory shortcut ID
+ *
+ *   <li>{@code android:enabled} Default is {@code true}.  Can be set to {@code false} in order
+ *   to disable a manifest shortcut that was published on a previous version with a custom
+ *   disabled message.  If a custom disabled message is not needed, then a manifest shortcut can
+ *   be simply removed from the xml file rather than keeping it with {@code enabled="false"}.
+ *
+ *   <li>{@code android:icon} Shortcut icon.
+ *
+ *   <li>{@code android:shortcutShortLabel} Mandatory shortcut short label.
+ *   See {@link ShortcutInfo.Builder#setShortLabel(CharSequence)}
+ *
+ *   <li>{@code android:shortcutLongLabel} Shortcut long label.
+ *   See {@link ShortcutInfo.Builder#setLongLabel(CharSequence)}
+ *
+ *   <li>{@code android:shortcutDisabledMessage} When {@code android:enabled} is set to
+ *   {@code false}, this can be used to set a custom disabled message.
+ *
+ *   <li>{@code intent} Intent to launch.  {@code android:action} is mandatory.
+ *   See <a href="{@docRoot}guide/topics/ui/settings.html#Intents">Using intents</a> for the
+ *   other supported tags.
+ * </ul>
+ *
+ * <h3>Updating Shortcuts v.s. Re-publishing New One with Different ID</h3>
+ * In order to avoid users' confusion, {@link #updateShortcuts(List)} should not be used to update
+ * a shortcut to something that is conceptually different.
+ *
+ * <p>For example, a phone application may publish the most frequently called contact as a dynamic
+ * shortcut.  Over the time, this contact may change, but when it changes the application should
+ * publish a new contact with a different ID with either
+ * {@link #setDynamicShortcuts(List)} or {@link #addDynamicShortcuts(List)}, rather than updating
+ * the existing shortcut with {@link #updateShortcuts(List)}.
+ *
+ * This is because when the shortcut is pinned, changing it to a different contact
+ * will likely confuse the user.
+ *
+ * <p>On the other hand, when the contact's information (e.g. the name or picture) has changed,
+ * then the application should use {@link #updateShortcuts(List)} so that the pinned shortcut
+ * will be updated too.
+ *
+ *
+ * <h3>Shortcut Display Order</h3>
+ * When the launcher show the shortcuts for a launcher icon, the showing order should be the
+ * following:
+ * <ul>
+ *   <li>First show manifest shortcuts
+ *   ({@link ShortcutInfo#isDeclaredInManifest()} is {@code true}),
+ *   and then dynamic shortcuts ({@link ShortcutInfo#isDynamic()} is {@code true}).
+ *   <li>Within each category, sort by {@link ShortcutInfo#getRank()}.
+ * </ul>
+ * <p>Shortcut ranks are non-negative sequential integers for each target activity.  Ranks of
+ * existing shortcuts can be updated with
+ * {@link #updateShortcuts(List)} ({@link #addDynamicShortcuts(List)} and
+ * {@link #setDynamicShortcuts(List)} may be used too).
+ *
+ * <p>Ranks will be auto-adjusted so that they're unique for each target activity for each category
+ * (dynamic or manifest).  For example, if there are 3 dynamic shortcuts with ranks 0, 1 and 2,
+ * adding another dynamic shortcut with rank = 1 means to place this shortcut at the second
+ * position.  The third and forth shortcuts (that were originally second and third) will be adjusted
+ * to 2 and 3 respectively.
+ *
+ * <h3>Rate Limiting</h3>
+ *
+ * Calls to {@link #setDynamicShortcuts(List)}, {@link #addDynamicShortcuts(List)} and
+ * {@link #updateShortcuts(List)} may be rate-limited when called by background applications (i.e.
+ * applications with no foreground activity or service).  When rate-limited, these APIs will return
+ * {@code false}.
+ *
+ * <p>Applications with a foreground activity or service will not be rate-limited.
+ *
+ * <p>Rate-limiting will be reset upon certain events, so that even background applications
+ * will be able to call these APIs again (until they are rate-limited again).
+ * <ul>
+ *   <li>When an application comes to foreground.
+ *   <li>When the system locale changes.
+ *   <li>When the user performs "inline reply" on a notification.
+ * </ul>
+ *
+ * <h4>Resetting rate-limiting for testing</h4>
+ *
+ * If your application is rate-limited during development or testing, you can use the
+ * "Reset ShortcutManager rate-limiting" development option, or the following adb command to reset
+ * it.
+ * <pre>
+ * adb shell cmd shortcut reset-throttling [ --user USER-ID ]
+ * </pre>
+ *
+ * <h3>Handling System Locale Change</h3>
+ *
+ * Applications should update dynamic and pinned shortcuts when the system locale changes
+ * using the {@link Intent#ACTION_LOCALE_CHANGED} broadcast.
+ *
+ * <p>When the system locale changes, rate-limiting will be reset, so even background applications
+ * what were previously rate-limited will be able to call {@link #updateShortcuts(List)}.
  *
  *
  * <h3>Backup and Restore</h3>
  *
- * Pinned shortcuts will be backed up and restored across devices.  This means all information
- * within shortcuts, including IDs, must be meaningful on different devices.
+ * When an application has {@code android:allowBackup="true"} in its AndroidManifest.xml, pinned
+ * shortcuts will be backed up automatically and restored when the user sets up a new device.
+ *
+ * <h4>What will be backed up and what will not be backed up</h4>
  *
- * <p>Note that:
  * <ul>
- *     <li>Dynamic shortcuts will not be backed up or restored.
- *     <li>Icons of pinned shortcuts will <b>not</b> be backed up for performance reasons, unless
- *     they refer to resources.  Instead, launcher applications are supposed to back up and restore
- *     icons of pinned shortcuts by themselves, and thus from the user's point of view, pinned
- *     shortcuts will look to have icons restored.
+ *  <li>Pinned shortcuts will be backed up.  Bitmap icons will not be backed up by the system,
+ *  but launcher applications should back them up and restore them, so the user will still get
+ *  icons for pinned shortcuts on the launcher.  Applications can always use
+ *  {@link #updateShortcuts(List)} to re-publish icons.
+ *
+ *  <li>Manifest shortcuts will not be backed up, but when an application is re-installed on a new
+ *  device, they will be re-published from AndroidManifest.xml anyway.
+ *
+ *  <li>Dynamic shortcuts will <b>not</b> be backed up.
  * </ul>
  *
+ * <p>Because dynamic shortcuts will not restored, it is recommended that applications check
+ * currently published dynamic shortcuts with {@link #getDynamicShortcuts()} when they start,
+ * and re-publish dynamic shortcuts when necessary.
+ *
+ * <pre>
+ * public class MainActivity extends Activity {
+ *     public void onCreate(Bundle savedInstanceState) {
+ *         super.onCreate(savedInstanceState);
+ *
+ *         ShortcutManager shortcutManager = getSystemService(ShortcutManager.class);
+ *
+ *         if (shortcutManager.getDynamicShortcuts().size() == 0) {
+ *             // Application restored; re-publish dynamic shortcuts.
+ *
+ *             if (shortcutManager.getPinnedShortcuts().size() > 0) {
+ *                 // Pinned shortcuts have been restored.  use updateShortcuts() to make sure
+ *                 // they have up-to-date information.
+ *             }
+ *         }
+ *     }
+ *     :
+ *
+ * }
+ * </pre>
  *
- * <h3>APIs for launcher</h3>
  *
- * Launcher applications should use {@link LauncherApps} to get shortcuts that are published from
- * applications.  Launcher applications can also pin shortcuts with
- * {@link LauncherApps#pinShortcuts(String, List, UserHandle)}.
+ * <h4>Backup/restore and shortcut IDs</h4>
+ *
+ * Because pinned shortcuts will be backed up and restored on new devices, shortcut IDs should be
+ * meaningful across devices; that is, IDs should be either stable constant strings, or server-side
+ * identifiers, rather than identifiers generated locally that may not make sense on other devices.
+ *
+ *
+ * <h3>Report Shortcut Usage and Prediction</h3>
+ *
+ * Launcher applications may be capable of predicting which shortcuts will most likely be used at
+ * the moment with the shortcut usage history data.
+ *
+ * <p>In order to provide launchers with such data, publisher applications should report which
+ * shortcut is used with {@link #reportShortcutUsed(String)} when a shortcut is started,
+ * <b>or when an action equivalent to a shortcut is taken by the user even if it wasn't started
+ * with the shortcut</b>.
+ *
+ * <p>For example, suppose a GPS navigation application exposes "navigate to work" as a shortcut.
+ * Then it should report it when the user starts this shortcut, and also when the user navigates
+ * to work within the application without using the shortcut.  This helps the launcher application
+ * learn that the user wants to navigate to work at a certain time every weekday, so that the
+ * launcher can show this shortcut in a suggestion list.
+ *
+ * <h3>Launcher API</h3>
+ *
+ * {@link LauncherApps} provides APIs for launcher applications to access shortcuts.
  */
 public class ShortcutManager {
     private static final String TAG = "ShortcutManager";
@@ -110,14 +382,15 @@ public class ShortcutManager {
 
     /**
      * Publish a list of shortcuts.  All existing dynamic shortcuts from the caller application
-     * will be replaced.
+     * will be replaced.  If there's already pinned shortcuts with the same IDs, they will all be
+     * updated, unless they're immutable.
      *
      * <p>This API will be rate-limited.
      *
      * @return {@code true} if the call has succeeded. {@code false} if the call is rate-limited.
      *
-     * @throws IllegalArgumentException if {@code shortcutInfoList} contains more than
-     * {@link #getMaxShortcutCountPerActivity()} shortcuts.
+     * @throws IllegalArgumentException if {@link #getMaxShortcutCountPerActivity()} is exceeded,
+     * or trying to update immutable shortcuts.
      */
     public boolean setDynamicShortcuts(@NonNull List<ShortcutInfo> shortcutInfoList) {
         try {
@@ -129,8 +402,7 @@ public class ShortcutManager {
     }
 
     /**
-     * Return all dynamic shortcuts from the caller application.  The number of result items
-     * will not exceed the value returned by {@link #getMaxShortcutCountPerActivity()}.
+     * Return all dynamic shortcuts from the caller application.
      */
     @NonNull
     public List<ShortcutInfo> getDynamicShortcuts() {
@@ -143,7 +415,7 @@ public class ShortcutManager {
     }
 
     /**
-     * TODO Javadoc
+     * Return all manifest shortcuts from the caller application.
      */
     @NonNull
     public List<ShortcutInfo> getManifestShortcuts() {
@@ -157,14 +429,14 @@ public class ShortcutManager {
 
     /**
      * Publish list of dynamic shortcuts.  If there's already dynamic or pinned shortcuts with
-     * the same IDs, they will all be updated.
+     * the same IDs, they will all be updated, unless they're immutable.
      *
      * <p>This API will be rate-limited.
      *
      * @return {@code true} if the call has succeeded. {@code false} if the call is rate-limited.
      *
-     * @throws IllegalArgumentException if the caller application has already published the
-     * max number of dynamic shortcuts.
+     * @throws IllegalArgumentException if {@link #getMaxShortcutCountPerActivity()} is exceeded,
+     * or trying to update immutable shortcuts.
      */
     public boolean addDynamicShortcuts(@NonNull List<ShortcutInfo> shortcutInfoList) {
         try {
@@ -212,11 +484,14 @@ public class ShortcutManager {
     }
 
     /**
-     * Update all existing shortcuts with the same IDs.  Shortcuts may be pinned and/or dynamic.
+     * Update all existing shortcuts with the same IDs.  Target shortcuts may be pinned and/or
+     * dynamic, but may not be immutable.
      *
      * <p>This API will be rate-limited.
      *
      * @return {@code true} if the call has succeeded. {@code false} if the call is rate-limited.
+     *
+     * @throws IllegalArgumentException if trying to update immutable shortcuts.
      */
     public boolean updateShortcuts(List<ShortcutInfo> shortcutInfoList) {
         try {
@@ -228,7 +503,7 @@ public class ShortcutManager {
     }
 
     /**
-     * TODO Javadoc
+     * Disable pinned shortcuts.  See {@link ShortcutManager}'s class javadoc for details.
      */
     public void disableShortcuts(@NonNull List<String> shortcutIds) {
         try {
@@ -261,7 +536,8 @@ public class ShortcutManager {
     }
 
     /**
-     * TODO Javadoc
+     * Disable pinned shortcuts with a custom error message.
+     * See {@link ShortcutManager}'s class javadoc for details.
      */
     public void disableShortcuts(@NonNull List<String> shortcutIds, CharSequence disabledMessage) {
         try {
@@ -274,7 +550,7 @@ public class ShortcutManager {
     }
 
     /**
-     * TODO Javadoc
+     * Re-enable disabled pinned shortcuts.
      */
     public void enableShortcuts(@NonNull List<String> shortcutIds) {
         try {
@@ -293,7 +569,7 @@ public class ShortcutManager {
     }
 
     /**
-     * Return the max number of dynamic shortcuts + manifest shortcuts that each launcher icon
+     * Return the max number of dynamic and manifest shortcuts that each launcher icon
      * can have at a time.
      */
     public int getMaxShortcutCountPerActivity() {
@@ -362,12 +638,9 @@ public class ShortcutManager {
     }
 
     /**
-     * Applications that publish shortcuts should call this method whenever an action that's
-     * equivalent to an existing shortcut has been taken by the user.  This includes not only when
-     * the user manually taps a shortcut, but when the user takes an equivalent action within the
-     * application -- for example, when a music player application has a shortcut to playlist X,
-     * then the application should not only report it when the playlist is opened from the
-     * shortcut, but also when the user plays the playlist within the application.
+     * Applications that publish shortcuts should call this method whenever a shortcut is started
+     * or an action equivalent to a shortcut is taken.  See the {@link ShortcutManager} class
+     * javadoc for details.
      *
      * <p>The information is accessible via {@link UsageStatsManager#queryEvents}
      * Typically, launcher applications use this information to build a prediction model