Update the deprecation description per API review
Change-Id: If79ed1263aae5fc7db6e951051ebb6db20d971f5
Fix: 124882352
Test: build (tree hugger)
diff --git a/core/java/android/database/sqlite/SQLiteDatabase.java b/core/java/android/database/sqlite/SQLiteDatabase.java
index dffbd89..caf3e93 100644
--- a/core/java/android/database/sqlite/SQLiteDatabase.java
+++ b/core/java/android/database/sqlite/SQLiteDatabase.java
@@ -2655,26 +2655,24 @@
* Sets the maximum number of milliseconds that SQLite connection is allowed to be idle
* before it is closed and removed from the pool.
*
- * <p>DO NOT USE this method unless you fully understand the implication
- * of what it does.
- * A connection timeout allows the system to internally close a connection to a SQLite
- * database after a given timeout.
- * This is good for reducing app's memory consumption, but it has
- * side effects that are hard to predict. For example, SQLite internally maintains
- * a lot of "per-connection" states that apps can typically modify with a {@code PRAGMA}
- * statement, and such states will be reset once the connection is closed.
- * The system does not provide a callback that would allow apps to
- * reconfigure a newly created connection and thus there's no way to re-configure
- * connections when they're re-made internally. Do not use it unless you're sure
- * your app uses no per-connection states.
+ * <p><b>DO NOT USE</b> this method.
+ * This feature has negative side effects that are very hard to foresee.
+ * <p>A connection timeout allows the system to internally close a connection to
+ * a SQLite database after a given timeout, which is good for reducing app's memory
+ * consumption.
+ * <b>However</b> the side effect is it <b>will reset all of SQLite's per-connection
+ * states</b>, which are typically modified with a {@code PRAGMA} statement, and
+ * these states <b>will not be restored</b> when a connection is re-established
+ * internally, and the system does not provide a callback for an app to reconfigure a
+ * connection.
+ * This feature may only be used if an app relies on none of such per-connection states.
*
* @param idleConnectionTimeoutMs timeout in milliseconds. Use {@link Long#MAX_VALUE}
* to allow unlimited idle connections.
*
* @see SQLiteOpenHelper#setIdleConnectionTimeout(long)
*
- * @deprecated DO NOT USE this method unless you fully understand the implication
- * of what it does.
+ * @deprecated DO NOT USE this method. See the javadoc for the details.
*/
@NonNull
@Deprecated
diff --git a/core/java/android/database/sqlite/SQLiteOpenHelper.java b/core/java/android/database/sqlite/SQLiteOpenHelper.java
index 8163c4d..62cec0e 100644
--- a/core/java/android/database/sqlite/SQLiteOpenHelper.java
+++ b/core/java/android/database/sqlite/SQLiteOpenHelper.java
@@ -267,8 +267,8 @@
* <p>This method should be called from the constructor of the subclass,
* before opening the database
*
- * <p>DO NOT USE this method unless you fully understand the implication
- * of what it does.
+ * <p><b>DO NOT USE</b> this method.
+ * This feature has negative side effects that are very hard to foresee.
* See the javadoc of
* {@link SQLiteDatabase.OpenParams.Builder#setIdleConnectionTimeout(long)}
* for the details.
@@ -278,8 +278,9 @@
*
* @see SQLiteDatabase.OpenParams.Builder#setIdleConnectionTimeout(long)
*
- * @deprecated DO NOT USE this method unless you fully understand the implication
- * of what it does.
+ * @deprecated DO NOT USE this method. See the javadoc of
+ * {@link SQLiteDatabase.OpenParams.Builder#setIdleConnectionTimeout(long)}
+ * for the details.
*/
@Deprecated
public void setIdleConnectionTimeout(@IntRange(from = 0) final long idleConnectionTimeoutMs) {