Merge "Update process importance documentation." into jb-dev

4 files changed, 71 insertions, 7 deletions

diff --git a/core/java/android/app/ActivityManager.java b/core/java/android/app/ActivityManager.java
index 11b4c3ad831e..7dce2d3d9950 100644
--- a/core/java/android/app/ActivityManager.java
+++ b/core/java/android/app/ActivityManager.java
@@ -502,7 +502,16 @@ public class ActivityManager {
     /**
      * Return a list of the tasks that the user has recently launched, with
      * the most recent being first and older ones after in order.
-     * 
+     *
+     * <p><b>Note: this method is only intended for debugging and presenting
+     * task management user interfaces</b>.  This should never be used for
+     * core logic in an application, such as deciding between different
+     * behaviors based on the information found here.  Such uses are
+     * <em>not</em> supported, and will likely break in the future.  For
+     * example, if multiple applications can be actively running at the
+     * same time, assumptions made about the meaning of the data here for
+     * purposes of control flow will be incorrect.</p>
+     *
      * @param maxNum The maximum number of entries to return in the list.  The
      * actual number returned may be smaller, depending on how many tasks the
      * user has started and the maximum number the system can remember.
@@ -669,6 +678,15 @@ public class ActivityManager {
      * can be restarted in its previous state when next brought to the
      * foreground.
      *
+     * <p><b>Note: this method is only intended for debugging and presenting
+     * task management user interfaces</b>.  This should never be used for
+     * core logic in an application, such as deciding between different
+     * behaviors based on the information found here.  Such uses are
+     * <em>not</em> supported, and will likely break in the future.  For
+     * example, if multiple applications can be actively running at the
+     * same time, assumptions made about the meaning of the data here for
+     * purposes of control flow will be incorrect.</p>
+     *
      * @param maxNum The maximum number of entries to return in the list.  The
      * actual number returned may be smaller, depending on how many tasks the
      * user has started.
@@ -1016,7 +1034,10 @@ public class ActivityManager {
 
     /**
      * Return a list of the services that are currently running.
-     * 
+     *
+     * <p><b>Note: this method is only intended for debugging or implementing
+     * service management type user interfaces.</b></p>
+     *
      * @param maxNum The maximum number of entries to return in the list.  The
      * actual number returned may be smaller, depending on how many services
      * are running.
@@ -1128,6 +1149,16 @@ public class ActivityManager {
         }
     }
 
+    /**
+     * Return general information about the memory state of the system.  This
+     * can be used to help decide how to manage your own memory, though note
+     * that polling is not recommended and
+     * {@link android.content.ComponentCallbacks2#onTrimMemory(int)
+     * ComponentCallbacks2.onTrimMemory(int)} is the preferred way to do this.
+     * Also see {@link #getMyMemoryState} for how to retrieve the current trim
+     * level of your process as needed, which gives a better hint for how to
+     * manage its memory.
+     */
     public void getMemoryInfo(MemoryInfo outInfo) {
         try {
             ActivityManagerNative.getDefault().getMemoryInfo(outInfo);
@@ -1497,6 +1528,9 @@ public class ActivityManager {
      * Returns a list of application processes installed on external media
      * that are running on the device.
      *
+     * <p><b>Note: this method is only intended for debugging or building
+     * a user-facing process management UI.</b></p>
+     *
      * @return Returns a list of ApplicationInfo records, or null if none
      * This list ordering is not specified.
      * @hide
@@ -1511,7 +1545,10 @@ public class ActivityManager {
 
     /**
      * Returns a list of application processes that are running on the device.
-     * 
+     *
+     * <p><b>Note: this method is only intended for debugging or building
+     * a user-facing process management UI.</b></p>
+     *
      * @return Returns a list of RunningAppProcessInfo records, or null if there are no
      * running processes (it will not return an empty list).  This list ordering is not
      * specified.
@@ -1544,7 +1581,10 @@ public class ActivityManager {
 
     /**
      * Return information about the memory usage of one or more processes.
-     * 
+     *
+     * <p><b>Note: this method is only intended for debugging or building
+     * a user-facing process management UI.</b></p>
+     *
      * @param pids The pids of the processes whose memory usage is to be
      * retrieved.
      * @return Returns an array of memory information, one for each
diff --git a/core/java/android/app/WallpaperManager.java b/core/java/android/app/WallpaperManager.java
index 6f19934a1bf0..3824f44ffc4d 100644
--- a/core/java/android/app/WallpaperManager.java
+++ b/core/java/android/app/WallpaperManager.java
@@ -637,6 +637,14 @@ public class WallpaperManager {
      * wallpaper it would like to use.  This allows such applications to have
      * a virtual wallpaper that is larger than the physical screen, matching
      * the size of their workspace.
+     *
+     * <p>Note developers, who don't seem to be reading this.  This is
+     * for <em>home screens</em> to tell what size wallpaper they would like.
+     * Nobody else should be calling this!  Certainly not other non-home-screen
+     * apps that change the wallpaper.  Those apps are supposed to
+     * <b>retrieve</b> the suggested size so they can construct a wallpaper
+     * that matches it.
+     *
      * @param minimumWidth Desired minimum width
      * @param minimumHeight Desired minimum height
      */
diff --git a/core/java/android/content/ComponentCallbacks2.java b/core/java/android/content/ComponentCallbacks2.java
index 85294dd00c9c..a3b4e5efb583 100644
--- a/core/java/android/content/ComponentCallbacks2.java
+++ b/core/java/android/content/ComponentCallbacks2.java
@@ -88,7 +88,11 @@ public interface ComponentCallbacks2 extends ComponentCallbacks {
      * should never compare to exact values of the level, since new intermediate
      * values may be added -- you will typically want to compare if the value
      * is greater or equal to a level you are interested in.
-     * 
+     *
+     * <p>To retrieve the processes current trim level at any point, you can
+     * use {@link android.app.ActivityManager#getMyMemoryState
+     * ActivityManager.getMyMemoryState(RunningAppProcessInfo)}.
+     *
      * @param level The context of the trim, giving a hint of the amount of
      * trimming the application may like to perform.  May be
      * {@link #TRIM_MEMORY_COMPLETE}, {@link #TRIM_MEMORY_MODERATE},
diff --git a/core/java/android/content/Intent.java b/core/java/android/content/Intent.java
index 665333693e1a..d0d9bd6c5e30 100644
--- a/core/java/android/content/Intent.java
+++ b/core/java/android/content/Intent.java
@@ -1624,8 +1624,20 @@ public class Intent implements Parcelable, Cloneable {
     /**
      * Broadcast Action:  The current system wallpaper has changed.  See
      * {@link android.app.WallpaperManager} for retrieving the new wallpaper.
-     */
-    @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
+     * This should <em>only</em> be used to determine when the wallpaper
+     * has changed to show the new wallpaper to the user.  You should certainly
+     * never, in response to this, change the wallpaper or other attributes of
+     * it such as the suggested size.  That would be crazy, right?  You'd cause
+     * all kinds of loops, especially if other apps are doing similar things,
+     * right?  Of course.  So please don't do this.
+     *
+     * @deprecated Modern applications should use
+     * {@link android.view.WindowManager.LayoutParams#FLAG_SHOW_WALLPAPER
+     * WindowManager.LayoutParams.FLAG_SHOW_WALLPAPER} to have the wallpaper
+     * shown behind their UI, rather than watching for this broadcast and
+     * rendering the wallpaper on their own.
+     */
+    @Deprecated @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
     public static final String ACTION_WALLPAPER_CHANGED = "android.intent.action.WALLPAPER_CHANGED";
     /**
      * Broadcast Action: The current device {@link android.content.res.Configuration}