Fix issue #123661377: API Review: MODE_FOREGROUND
Expand documentation of MODE_FOREGROUND to better explain its
subtleties.
Bug: 123661377
Test: built docs
Change-Id: I522f439d677ee5c1000047c2017076fc36c26118
diff --git a/core/java/android/app/AppOpsManager.java b/core/java/android/app/AppOpsManager.java
index 9ee2f03..b23f343 100644
--- a/core/java/android/app/AppOpsManager.java
+++ b/core/java/android/app/AppOpsManager.java
@@ -189,9 +189,19 @@
/**
* Special mode that means "allow only when app is in foreground." This is <b>not</b>
- * returned from {@link #checkOp}, {@link #noteOp}, {@link #startOp}; rather, when this
- * mode is set, these functions will return {@link #MODE_ALLOWED} when the app being
- * checked is currently in the foreground, otherwise {@link #MODE_IGNORED}.
+ * returned from {@link #unsafeCheckOp}, {@link #noteOp}, {@link #startOp}. Rather,
+ * {@link #unsafeCheckOp} will always return {@link #MODE_ALLOWED} (because it is always
+ * possible for it to be ultimately allowed, depending on the app's background state),
+ * and {@link #noteOp} and {@link #startOp} will return {@link #MODE_ALLOWED} when the app
+ * being checked is currently in the foreground, otherwise {@link #MODE_IGNORED}.
+ *
+ * <p>The only place you will this normally see this value is through
+ * {@link #unsafeCheckOpRaw}, which returns the actual raw mode of the op. Note that because
+ * you can't know the current state of the app being checked (and it can change at any
+ * point), you can only treat the result here as an indication that it will vary between
+ * {@link #MODE_ALLOWED} and {@link #MODE_IGNORED} depending on changes in the background
+ * state of the app. You thus must always use {@link #noteOp} or {@link #startOp} to do
+ * the actual check for access to the op.</p>
*/
public static final int MODE_FOREGROUND = 4;