From 8ef6970cf5b779a5a69502cb07fd94d9190bccfd Mon Sep 17 00:00:00 2001
From: Joe Fernandez <joefernandez@google.com>
Date: Fri, 2 Sep 2011 14:32:22 -0700
Subject: [PATCH] docs: adding warning to managedQuery() JavaDoc about
 cursor.close()

Change-Id: I31ba29f1781f7d83342582e25cf6aad0c72aa103
---
 core/java/android/app/Activity.java | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/core/java/android/app/Activity.java b/core/java/android/app/Activity.java
index 41e3fdfb4ca83..034e3c7877663 100644
--- a/core/java/android/app/Activity.java
+++ b/core/java/android/app/Activity.java
@@ -1638,6 +1638,12 @@ public class Activity extends ContextThemeWrapper
      * or later, consider instead using {@link LoaderManager} instead, available
      * via {@link #getLoaderManager()}.</em>
      *
+     * <p><strong>Warning:</strong> Do not call {@link Cursor#close()} on a cursor obtained using
+     * this method, because the activity will do that for you at the appropriate time. However, if
+     * you call {@link #stopManagingCursor} on a cursor from a managed query, the system <em>will
+     * not</em> automatically close the cursor and, in that case, you must call
+     * {@link Cursor#close()}.</p>
+     * 
      * @param uri The URI of the content provider to query.
      * @param projection List of columns to return.
      * @param selection SQL WHERE clause.
@@ -1672,6 +1678,12 @@ public class Activity extends ContextThemeWrapper
      * or later, consider instead using {@link LoaderManager} instead, available
      * via {@link #getLoaderManager()}.</em>
      *
+     * <p><strong>Warning:</strong> Do not call {@link Cursor#close()} on a cursor obtained using
+     * this method, because the activity will do that for you at the appropriate time. However, if
+     * you call {@link #stopManagingCursor} on a cursor from a managed query, the system <em>will
+     * not</em> automatically close the cursor and, in that case, you must call
+     * {@link Cursor#close()}.</p>
+     * 
      * @param uri The URI of the content provider to query.
      * @param projection List of columns to return.
      * @param selection SQL WHERE clause.
@@ -1707,6 +1719,12 @@ public class Activity extends ContextThemeWrapper
      * or later, consider instead using {@link LoaderManager} instead, available
      * via {@link #getLoaderManager()}.</em>
      *
+     * <p><strong>Warning:</strong> Do not call {@link Cursor#close()} on cursor obtained from
+     * {@link #managedQuery}, because the activity will do that for you at the appropriate time.
+     * However, if you call {@link #stopManagingCursor} on a cursor from a managed query, the system
+     * <em>will not</em> automatically close the cursor and, in that case, you must call
+     * {@link Cursor#close()}.</p>
+     * 
      * @param c The Cursor to be managed.
      * 
      * @see #managedQuery(android.net.Uri , String[], String, String[], String)
@@ -1728,6 +1746,10 @@ public class Activity extends ContextThemeWrapper
      * {@link #startManagingCursor}, stop the activity's management of that
      * cursor.
      * 
+     * <p><strong>Warning:</strong> After calling this method on a cursor from a managed query,
+     * the system <em>will not</em> automatically close the cursor and you must call 
+     * {@link Cursor#close()}.</p>
+     * 
      * @param c The Cursor that was being managed.
      * 
      * @see #startManagingCursor