From fa962315a090905dcd9a3d909be7530b75bc9809 Mon Sep 17 00:00:00 2001
From: Esteban Talavera <etalavera@google.com>
Date: Mon, 9 Oct 2017 14:58:28 +0100
Subject: [PATCH] Update UsageStatsManager Javadoc to match implementation

Third party apps can get the permission to use those
APIs, and none of the APIs return null any more

Test: make docs
Change-Id: I989cb15ce239e8fc11e87cf5841cb5165b0f353a
---
 .../android/app/usage/UsageStatsManager.java  | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)

diff --git a/core/java/android/app/usage/UsageStatsManager.java b/core/java/android/app/usage/UsageStatsManager.java
index 051dccbd86c01..fd579fce34d83 100644
--- a/core/java/android/app/usage/UsageStatsManager.java
+++ b/core/java/android/app/usage/UsageStatsManager.java
@@ -48,10 +48,10 @@ import java.util.Map;
  * </pre>
  * A request for data in the middle of a time interval will include that interval.
  * <p/>
- * <b>NOTE:</b> This API requires the permission android.permission.PACKAGE_USAGE_STATS, which
- * is a system-level permission and will not be granted to third-party apps. However, declaring
- * the permission implies intention to use the API and the user of the device can grant permission
- * through the Settings application.
+ * <b>NOTE:</b> This API requires the permission android.permission.PACKAGE_USAGE_STATS.
+ * However, declaring the permission implies intention to use the API and the user of the device
+ * still needs to grant permission through the Settings application.
+ * See {@link android.provider.Settings#ACTION_USAGE_ACCESS_SETTINGS}
  */
 @SystemService(Context.USAGE_STATS_SERVICE)
 public final class UsageStatsManager {
@@ -122,7 +122,7 @@ public final class UsageStatsManager {
      * @param intervalType The time interval by which the stats are aggregated.
      * @param beginTime The inclusive beginning of the range of stats to include in the results.
      * @param endTime The exclusive end of the range of stats to include in the results.
-     * @return A list of {@link UsageStats} or null if none are available.
+     * @return A list of {@link UsageStats}
      *
      * @see #INTERVAL_DAILY
      * @see #INTERVAL_WEEKLY
@@ -139,7 +139,7 @@ public final class UsageStatsManager {
                 return slice.getList();
             }
         } catch (RemoteException e) {
-            // fallthrough and return null.
+            // fallthrough and return the empty list.
         }
         return Collections.emptyList();
     }
@@ -152,7 +152,7 @@ public final class UsageStatsManager {
      * @param intervalType The time interval by which the stats are aggregated.
      * @param beginTime The inclusive beginning of the range of stats to include in the results.
      * @param endTime The exclusive end of the range of stats to include in the results.
-     * @return A list of {@link ConfigurationStats} or null if none are available.
+     * @return A list of {@link ConfigurationStats}
      */
     public List<ConfigurationStats> queryConfigurations(int intervalType, long beginTime,
             long endTime) {
@@ -185,7 +185,7 @@ public final class UsageStatsManager {
                 return iter;
             }
         } catch (RemoteException e) {
-            // fallthrough and return null
+            // fallthrough and return empty result.
         }
         return sEmptyResults;
     }
@@ -197,8 +197,7 @@ public final class UsageStatsManager {
      *
      * @param beginTime The inclusive beginning of the range of stats to include in the results.
      * @param endTime The exclusive end of the range of stats to include in the results.
-     * @return A {@link java.util.Map} keyed by package name, or null if no stats are
-     *         available.
+     * @return A {@link java.util.Map} keyed by package name
      */
     public Map<String, UsageStats> queryAndAggregateUsageStats(long beginTime, long endTime) {
         List<UsageStats> stats = queryUsageStats(INTERVAL_BEST, beginTime, endTime);