Merge "Added more documentation for dialogMessage" into pi-dev

core/java/android/content/Intent.java

@@ -2289,9 +2289,8 @@ public class Intent implements Parcelable, Cloneable {
     /**
      * Activity Action: Started to show more details about why an application was suspended.
      *
-     * <p>Whenever the system detects an activity launch for a suspended app, it shows a dialog to
-     * the user to inform them of the state and present them an affordance to start this activity
-     * action to show more details about the reason for suspension.
+     * <p>Whenever the system detects an activity launch for a suspended app, this action can
+     * be used to show more details about the reason for suspension.
      *
      * <p>Apps holding {@link android.Manifest.permission#SUSPEND_APPS} must declare an activity
      * handling this intent and protect it with

core/java/android/content/pm/LauncherApps.java

@@ -229,7 +229,7 @@ public class LauncherApps {
          * <p>A suspending app with the permission {@code android.permission.SUSPEND_APPS} can
          * optionally provide a {@link Bundle} of extra information that it deems helpful for the
          * launcher to handle the suspended state of these packages. The contents of this
-         * {@link Bundle} supposed to be a contract between the suspending app and the launcher.
+         * {@link Bundle} are supposed to be a contract between the suspending app and the launcher.
          *
          * @param packageNames The names of the packages that have just been suspended.
          * @param user the user for which the given packages were suspended.

core/java/android/content/pm/PackageManager.java

@@ -68,6 +68,7 @@ import java.io.File;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.util.List;
+import java.util.Locale;
 
 /**
  * Class for retrieving various kinds of information related to the application
@@ -5527,15 +5528,23 @@ public abstract class PackageManager {
      *
      * <p>It doesn't remove the data or the actual package file. The application's notifications
      * will be hidden, any of its started activities will be stopped and it will not be able to
-     * show toasts or dialogs or ring the device. When the user tries to launch a suspended app, a
-     * system dialog with the given {@code dialogMessage} will be shown instead.</p>
+     * show toasts or system alert windows or ring the device.
+     *
+     * <p>When the user tries to launch a suspended app, a system dialog with the given
+     * {@code dialogMessage} will be shown instead. Since the message is supplied to the system as
+     * a {@link String}, the caller needs to take care of localization as needed.
+     * The dialog message can optionally contain a placeholder for the name of the suspended app.
+     * The system uses {@link String#format(Locale, String, Object...) String.format} to insert the
+     * app name into the message, so an example format string could be {@code "The app %1$s is
+     * currently suspended"}. This makes it easier for callers to provide a single message which
+     * works for all the packages being suspended in a single call.
      *
      * <p>The package must already be installed. If the package is uninstalled while suspended
      * the package will no longer be suspended. </p>
      *
      * <p>Optionally, the suspending app can provide extra information in the form of
      * {@link PersistableBundle} objects to be shared with the apps being suspended and the
-     * launcher to support customization that they might need to handle the suspended state. </p>
+     * launcher to support customization that they might need to handle the suspended state.
      *
      * <p>The caller must hold {@link Manifest.permission#SUSPEND_APPS} or
      * {@link Manifest.permission#MANAGE_USERS} to use this api.</p>
@@ -5552,8 +5561,8 @@ public abstract class PackageManager {
      * @param dialogMessage The message to be displayed to the user, when they try to launch a
      *                      suspended app.
      *
-     * @return an array of package names for which the suspended status is not set as requested in
-     * this method.
+     * @return an array of package names for which the suspended status could not be set as
+     * requested in this method.
      *
      * @hide
      */