Deprecate a bunch of APIs.

And clean up some documentation.

Change-Id: I7882183b3daf883b7ac6098d19f88dc7cfbcdf61

8 files changed, 132 insertions, 12 deletions

diff --git a/core/java/android/app/Activity.java b/core/java/android/app/Activity.java
index ed39457..389d4856 100644
--- a/core/java/android/app/Activity.java
+++ b/core/java/android/app/Activity.java
@@ -1437,6 +1437,10 @@ public class Activity extends ContextThemeWrapper
     }
     
     /**
+     * @deprecated Use the new {@link Fragment} API
+     * {@link Fragment#setRetainInstance(boolean)} instead; this is also
+     * available on older platforms through the Android compatibility package.
+     *
      * Retrieve the non-configuration instance data that was previously
      * returned by {@link #onRetainNonConfigurationInstance()}.  This will
      * be available from the initial {@link #onCreate} and
@@ -1453,12 +1457,17 @@ public class Activity extends ContextThemeWrapper
      * @return Returns the object previously returned by
      * {@link #onRetainNonConfigurationInstance()}.
      */
+    @Deprecated
     public Object getLastNonConfigurationInstance() {
         return mLastNonConfigurationInstances != null
                 ? mLastNonConfigurationInstances.activity : null;
     }
     
     /**
+     * @deprecated Use the new {@link Fragment} API
+     * {@link Fragment#setRetainInstance(boolean)} instead; this is also
+     * available on older platforms through the Android compatibility package.
+     *
      * Called by the system, as part of destroying an
      * activity due to a configuration change, when it is known that a new
      * instance will immediately be created for the new configuration.  You
@@ -1674,6 +1683,10 @@ public class Activity extends ContextThemeWrapper
     }
 
     /**
+     * @deprecated Use the new {@link android.content.CursorLoader} class with
+     * {@link LoaderManager} instead; this is also
+     * available on older platforms through the Android compatibility package.
+     *
      * This method allows the activity to take care of managing the given
      * {@link Cursor}'s lifecycle for you based on the activity's lifecycle.
      * That is, when the activity is stopped it will automatically call
@@ -1689,8 +1702,6 @@ public class Activity extends ContextThemeWrapper
      * 
      * @see #managedQuery(android.net.Uri , String[], String, String[], String)
      * @see #stopManagingCursor
-     *
-     * @deprecated Use {@link CursorLoader} instead.
      */
     @Deprecated
     public void startManagingCursor(Cursor c) {
@@ -1700,6 +1711,10 @@ public class Activity extends ContextThemeWrapper
     }
 
     /**
+     * @deprecated Use the new {@link android.content.CursorLoader} class with
+     * {@link LoaderManager} instead; this is also
+     * available on older platforms through the Android compatibility package.
+     *
      * Given a Cursor that was previously given to
      * {@link #startManagingCursor}, stop the activity's management of that
      * cursor.
@@ -1707,8 +1722,6 @@ public class Activity extends ContextThemeWrapper
      * @param c The Cursor that was being managed.
      * 
      * @see #startManagingCursor
-     *
-     * @deprecated Use {@link CursorLoader} instead.
      */
     @Deprecated
     public void stopManagingCursor(Cursor c) {
@@ -2714,6 +2727,10 @@ public class Activity extends ContextThemeWrapper
     }
 
     /**
+     * @deprecated Use the new {@link DialogFragment} class with
+     * {@link FragmentManager} instead; this is also
+     * available on older platforms through the Android compatibility package.
+     *
      * Callback for creating dialogs that are managed (saved and restored) for you
      * by the activity.  The default implementation calls through to
      * {@link #onCreateDialog(int)} for compatibility.
@@ -2742,6 +2759,7 @@ public class Activity extends ContextThemeWrapper
      * @see #dismissDialog(int)
      * @see #removeDialog(int)
      */
+    @Deprecated
     protected Dialog onCreateDialog(int id, Bundle args) {
         return onCreateDialog(id);
     }
@@ -2756,6 +2774,10 @@ public class Activity extends ContextThemeWrapper
     }
 
     /**
+     * @deprecated Use the new {@link DialogFragment} class with
+     * {@link FragmentManager} instead; this is also
+     * available on older platforms through the Android compatibility package.
+     *
      * Provides an opportunity to prepare a managed dialog before it is being
      * shown.  The default implementation calls through to
      * {@link #onPrepareDialog(int, Dialog)} for compatibility.
@@ -2775,20 +2797,30 @@ public class Activity extends ContextThemeWrapper
      * @see #dismissDialog(int)
      * @see #removeDialog(int)
      */
+    @Deprecated
     protected void onPrepareDialog(int id, Dialog dialog, Bundle args) {
         onPrepareDialog(id, dialog);
     }
 
     /**
+     * @deprecated Use the new {@link DialogFragment} class with
+     * {@link FragmentManager} instead; this is also
+     * available on older platforms through the Android compatibility package.
+     *
      * Simple version of {@link #showDialog(int, Bundle)} that does not
      * take any arguments.  Simply calls {@link #showDialog(int, Bundle)}
      * with null arguments.
      */
+    @Deprecated
     public final void showDialog(int id) {
         showDialog(id, null);
     }
 
     /**
+     * @deprecated Use the new {@link DialogFragment} class with
+     * {@link FragmentManager} instead; this is also
+     * available on older platforms through the Android compatibility package.
+     *
      * Show a dialog managed by this activity.  A call to {@link #onCreateDialog(int, Bundle)}
      * will be made with the same id the first time this is called for a given
      * id.  From thereafter, the dialog will be automatically saved and restored.
@@ -2814,6 +2846,7 @@ public class Activity extends ContextThemeWrapper
      * @see #dismissDialog(int)
      * @see #removeDialog(int)
      */
+    @Deprecated
     public final boolean showDialog(int id, Bundle args) {
         if (mManagedDialogs == null) {
             mManagedDialogs = new SparseArray<ManagedDialog>();
@@ -2835,6 +2868,10 @@ public class Activity extends ContextThemeWrapper
     }
 
     /**
+     * @deprecated Use the new {@link DialogFragment} class with
+     * {@link FragmentManager} instead; this is also
+     * available on older platforms through the Android compatibility package.
+     *
      * Dismiss a dialog that was previously shown via {@link #showDialog(int)}.
      *
      * @param id The id of the managed dialog.
@@ -2847,6 +2884,7 @@ public class Activity extends ContextThemeWrapper
      * @see #showDialog(int)
      * @see #removeDialog(int)
      */
+    @Deprecated
     public final void dismissDialog(int id) {
         if (mManagedDialogs == null) {
             throw missingDialog(id);
@@ -2869,6 +2907,10 @@ public class Activity extends ContextThemeWrapper
     }
 
     /**
+     * @deprecated Use the new {@link DialogFragment} class with
+     * {@link FragmentManager} instead; this is also
+     * available on older platforms through the Android compatibility package.
+     *
      * Removes any internal references to a dialog managed by this Activity.
      * If the dialog is showing, it will dismiss it as part of the clean up.
      *
@@ -2886,6 +2928,7 @@ public class Activity extends ContextThemeWrapper
      * @see #showDialog(int)
      * @see #dismissDialog(int)
      */
+    @Deprecated
     public final void removeDialog(int id) {
         if (mManagedDialogs != null) {
             final ManagedDialog md = mManagedDialogs.get(id);
diff --git a/core/java/android/app/Fragment.java b/core/java/android/app/Fragment.java
index dd158f9..6f0bbd7 100644
--- a/core/java/android/app/Fragment.java
+++ b/core/java/android/app/Fragment.java
@@ -164,11 +164,21 @@ final class FragmentState implements Parcelable {
  *
  * <p>Topics covered here:
  * <ol>
+ * <li><a href="#OlderPlatforms">Older Platforms</a>
  * <li><a href="#Lifecycle">Lifecycle</a>
  * <li><a href="#Layout">Layout</a>
  * <li><a href="#BackStack">Back Stack</a>
  * </ol>
  *
+ * <a name="OlderPlatforms"></a>
+ * <h3>Older Platforms</h3>
+ *
+ * While the Fragment API was introduced in
+ * {@link android.os.Build.VERSION_CODES#HONEYCOMB}, a version of the API
+ * is also available for use on older platforms.  See the blog post
+ * <a href="http://android-developers.blogspot.com/2011/03/fragments-for-all.html">
+ * Fragments For All</a> for more details.
+ *
  * <a name="Lifecycle"></a>
  * <h3>Lifecycle</h3>
  *
diff --git a/core/java/android/app/KeyguardManager.java b/core/java/android/app/KeyguardManager.java
index a601fbf..0fe7b5c 100644
--- a/core/java/android/app/KeyguardManager.java
+++ b/core/java/android/app/KeyguardManager.java
@@ -35,6 +35,12 @@ public class KeyguardManager {
     private IWindowManager mWM;
 
     /**
+     * @deprecated Use {@link android.view.WindowManager.LayoutParams#FLAG_DISMISS_KEYGUARD}
+     * and/or {@link android.view.WindowManager.LayoutParams#FLAG_SHOW_WHEN_LOCKED}
+     * instead; this allows you to seamlessly hide the keyguard as your application
+     * moves in and out of the foreground and does not require that any special
+     * permissions be requested.
+     *
      * Handle returned by {@link KeyguardManager#newKeyguardLock} that allows
      * you to disable / reenable the keyguard.
      */
@@ -103,6 +109,12 @@ public class KeyguardManager {
     }
 
     /**
+     * @deprecated Use {@link android.view.WindowManager.LayoutParams#FLAG_DISMISS_KEYGUARD}
+     * and/or {@link android.view.WindowManager.LayoutParams#FLAG_SHOW_WHEN_LOCKED}
+     * instead; this allows you to seamlessly hide the keyguard as your application
+     * moves in and out of the foreground and does not require that any special
+     * permissions be requested.
+     *
      * Enables you to lock or unlock the keyboard. Get an instance of this class by
      * calling {@link android.content.Context#getSystemService(java.lang.String) Context.getSystemService()}. 
      * This class is wrapped by {@link android.app.KeyguardManager KeyguardManager}.
@@ -112,6 +124,7 @@ public class KeyguardManager {
      * @return A {@link KeyguardLock} handle to use to disable and reenable the
      *   keyguard.
      */
+    @Deprecated
     public KeyguardLock newKeyguardLock(String tag) {
         return new KeyguardLock(tag);
     }
@@ -168,6 +181,12 @@ public class KeyguardManager {
     }
 
     /**
+     * @deprecated Use {@link android.view.WindowManager.LayoutParams#FLAG_DISMISS_KEYGUARD}
+     * and/or {@link android.view.WindowManager.LayoutParams#FLAG_SHOW_WHEN_LOCKED}
+     * instead; this allows you to seamlessly hide the keyguard as your application
+     * moves in and out of the foreground and does not require that any special
+     * permissions be requested.
+     *
      * Exit the keyguard securely.  The use case for this api is that, after
      * disabling the keyguard, your app, which was granted permission to
      * disable the keyguard and show a limited amount of information deemed
@@ -181,6 +200,7 @@ public class KeyguardManager {
      *   it is safe to launch anything that would normally be considered safe
      *   once the user has gotten past the keyguard.
      */
+    @Deprecated
     public void exitKeyguardSecurely(final OnKeyguardExitResult callback) {
         try {
             mWM.exitKeyguardSecurely(new IOnKeyguardExitResult.Stub() {
diff --git a/core/java/android/app/LoaderManager.java b/core/java/android/app/LoaderManager.java
index 1ee386d..164141c 100644
--- a/core/java/android/app/LoaderManager.java
+++ b/core/java/android/app/LoaderManager.java
@@ -34,12 +34,18 @@ import java.lang.reflect.Modifier;
  * {@link android.content.CursorLoader}, however applications are free to write
  * their own loaders for loading other types of data.
  *
+ * While the LoaderManager API was introduced in
+ * {@link android.os.Build.VERSION_CODES#HONEYCOMB}, a version of the API
+ * is also available for use on older platforms.  See the blog post
+ * <a href="http://android-developers.blogspot.com/2011/03/fragments-for-all.html">
+ * Fragments For All</a> for more details.
+ *
  * <p>As an example, here is the full implementation of a {@link Fragment}
  * that displays a {@link android.widget.ListView} containing the results of
  * a query against the contacts content provider.  It uses a
  * {@link android.content.CursorLoader} to manage the query on the provider.
  *
- * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentListCursorLoader.java
+ * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/LoaderCursor.java
  *      fragment_cursor}
  */
 public abstract class LoaderManager {
diff --git a/core/java/android/content/AsyncTaskLoader.java b/core/java/android/content/AsyncTaskLoader.java
index 383cb6b..0b54396 100644
--- a/core/java/android/content/AsyncTaskLoader.java
+++ b/core/java/android/content/AsyncTaskLoader.java
@@ -27,7 +27,24 @@ import java.io.PrintWriter;
 import java.util.concurrent.CountDownLatch;
 
 /**
- * Abstract Loader that provides an {@link AsyncTask} to do the work.
+ * Abstract Loader that provides an {@link AsyncTask} to do the work.  See
+ * {@link Loader} and {@link android.app.LoaderManager} for more details.
+ *
+ * <p>Here is an example implementation of an AsyncTaskLoader subclass that
+ * loads the currently installed applications from the package manager.  This
+ * implementation takes care of retrieving the application labels and sorting
+ * its result set from them, monitoring for changes to the installed
+ * applications, and rebuilding the list when a change in configuration requires
+ * this (such as a locale change).
+ *
+ * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/LoaderCustom.java
+ *      loader}
+ *
+ * <p>An example implementation of a fragment that uses the above loader to show
+ * the currently installed applications in a list is below.
+ *
+ * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/LoaderCustom.java
+ *      fragment}
  *
  * @param <D> the data type to be loaded.
  */
diff --git a/core/java/android/content/Loader.java b/core/java/android/content/Loader.java
index a9d6117..4e70b74 100644
--- a/core/java/android/content/Loader.java
+++ b/core/java/android/content/Loader.java
@@ -26,7 +26,7 @@ import java.io.PrintWriter;
 /**
  * An abstract class that performs asynchronous loading of data. While Loaders are active
  * they should monitor the source of their data and deliver new results when the contents
- * change.
+ * change.  See {@link android.app.LoaderManager} for more detail.
  *
  * <p><b>Note on threading:</b> Clients of loaders should as a rule perform
  * any calls on to a Loader from the main thread of their process (that is,
@@ -36,7 +36,10 @@ import java.io.PrintWriter;
  * be done on the main thread.</p>
  *
  * <p>Subclasses generally must implement at least {@link #onStartLoading()},
- * {@link #onStopLoading()}, {@link #onForceLoad()}, and {@link #onReset()}.
+ * {@link #onStopLoading()}, {@link #onForceLoad()}, and {@link #onReset()}.</p>
+ *
+ * <p>Most implementations should not derive directly from this class, but
+ * instead inherit from {@link AsyncTaskLoader}.</p>
  *
  * @param <D> The result returned when the load is complete
  */
@@ -76,8 +79,12 @@ public class Loader<D> {
     }
 
     /**
-     * Stores away the application context associated with context. Since Loaders can be used
-     * across multiple activities it's dangerous to store the context directly.
+     * Stores away the application context associated with context.
+     * Since Loaders can be used across multiple activities it's dangerous to
+     * store the context directly; always use {@link #getContext()} to retrieve
+     * the Loader's Context, don't use the constructor argument directly.
+     * The Context returned by {@link #getContext} is safe to use across
+     * Activity instances.
      *
      * @param context used to retrieve the application context.
      */
diff --git a/core/java/android/os/PowerManager.java b/core/java/android/os/PowerManager.java
index 57fdb0c..c830f7a 100644
--- a/core/java/android/os/PowerManager.java
+++ b/core/java/android/os/PowerManager.java
@@ -131,14 +131,25 @@ public class PowerManager
     /**
      * Wake lock that ensures that the screen and keyboard are on at
      * full brightness.
+     *
+     * <p class="note">Most applications should strongly consider using
+     * {@link android.view.WindowManager.LayoutParams#FLAG_KEEP_SCREEN_ON}.
+     * This window flag will be correctly managed by the platform
+     * as the user moves between applications and doesn't require a special permission.</p>
      */
     public static final int FULL_WAKE_LOCK = WAKE_BIT_CPU_WEAK | WAKE_BIT_SCREEN_BRIGHT 
                                             | WAKE_BIT_KEYBOARD_BRIGHT;
 
     /**
+     * @deprecated Most applications should use
+     * {@link android.view.WindowManager.LayoutParams#FLAG_KEEP_SCREEN_ON} instead
+     * of this type of wake lock, as it will be correctly managed by the platform
+     * as the user moves between applications and doesn't require a special permission.
+     *
      * Wake lock that ensures that the screen is on at full brightness;
      * the keyboard backlight will be allowed to go off.
      */
+    @Deprecated
     public static final int SCREEN_BRIGHT_WAKE_LOCK = WAKE_BIT_CPU_WEAK | WAKE_BIT_SCREEN_BRIGHT;
 
     /**
@@ -384,6 +395,11 @@ public class PowerManager
      *wl.release();
      * }
      *
+     * <p class="note">If using this to keep the screen on, you should strongly consider using
+     * {@link android.view.WindowManager.LayoutParams#FLAG_KEEP_SCREEN_ON} instead.
+     * This window flag will be correctly managed by the platform
+     * as the user moves between applications and doesn't require a special permission.</p>
+     *
      * @param flags Combination of flag values defining the requested behavior of the WakeLock.
      * @param tag Your class name (or other tag) for debugging purposes.
      *
diff --git a/core/java/android/view/inputmethod/InputConnection.java b/core/java/android/view/inputmethod/InputConnection.java
index ea9e402..a6639d1 100644
--- a/core/java/android/view/inputmethod/InputConnection.java
+++ b/core/java/android/view/inputmethod/InputConnection.java
@@ -26,8 +26,9 @@ import android.view.KeyEvent;
  * is used to perform such things as reading text around the cursor,
  * committing text to the text box, and sending raw key events to the application.
  * 
- * <p>Implementations of this interface should generally be done by
- * subclassing {@link BaseInputConnection}.
+ * <p>Applications should never directly implement this interface, but instead
+ * subclass from {@link BaseInputConnection}.  This will ensure that the
+ * application does not break when new methods are added to the interface.
  */
 public interface InputConnection {
     /**