Merge "Clean up javadoc." into nyc-dev

core/java/android/content/pm/ShortcutInfo.java

@@ -34,18 +34,20 @@ import com.android.internal.util.Preconditions;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
+// TODO Enhance javadoc
 /**
- * TODO Enhance javadoc
  *
- * Represents a shortcut form an application.
+ * Represents a shortcut from an application.
  *
- * Notes...
- * - If an {@link Icon} is of a resource, then we'll just persist the package name and resource ID.
+ * <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>
  *
- *   Otherwise, the bitmap will be fetched when it's registered to ShortcutManager, then *shrunk*
- *   if necessary, and persisted.
- *
- *   We will disallow byte[] icons, because they can easily go over binder size limit.
+ * @see {@link ShortcutManager}.
  */
 public class ShortcutInfo implements Parcelable {
     /* @hide */
@@ -371,6 +373,9 @@ public class ShortcutInfo implements Parcelable {
 
         /**
          * Sets the title of a shortcut.  This is a mandatory field.
+         *
+         * <p>This field is intended for a concise description of a shortcut displayed under
+         * an icon.  The recommend max length is 10 characters.
          */
         @NonNull
         public Builder setTitle(@NonNull String title) {
@@ -380,6 +385,9 @@ public class ShortcutInfo implements Parcelable {
 
         /**
          * Sets the text of a shortcut.  This is an optional field.
+         *
+         * <p>This field is intended to be more descriptive than the shortcut title.
+         * The recommend max length is 25 characters.
          */
         @NonNull
         public Builder setText(@NonNull String text) {

core/java/android/content/pm/ShortcutManager.java

@@ -19,15 +19,13 @@ import android.annotation.NonNull;
 import android.content.Context;
 import android.os.RemoteException;
 import android.os.UserHandle;
-import android.util.Log;
 
 import com.android.internal.annotations.VisibleForTesting;
 
 import java.util.List;
 
+// TODO Enhance javadoc
 /**
- * TODO Enhance javadoc
- *
  * {@link ShortcutManager} manages shortcuts created by applications.
  *
  * <h3>Dynamic shortcuts and pinned shortcuts</h3>
@@ -66,15 +64,18 @@ import java.util.List;
  * {@link #getRemainingCallCount()} times until the rate-limiting counter is reset,
  * which happens at a certain time every day.
  *
- * <p>An applications can use {@link #getRateLimitResetTime()} to get the next reset time.
+ * <p>An application can use {@link #getRateLimitResetTime()} to get the next reset time.
+ *
+ * <p>For testing purposes, use "Developer Options" (found in the Settings menu) to reset the
+ * internal rate-limiting counter.  Automated tests can use the following ADB shell command to
+ * achieve the same effect:</p>
+ * <pre>adb shell cmd shortcut reset-throttling</pre>
  *
  * <h3>Backup and Restore</h3>
  *
  * Shortcuts will be backed up and restored across devices.  This means all information, including
  * IDs, must be meaningful on a different device.
  *
- * TODO: Define a Broadcast to let apps update shortcuts on a restored device.
- *
  * <h3>APIs for launcher</h3>
  *
  * Launcher applications should use {@link LauncherApps} to get shortcuts that are published from