Merge "BatteryManager: update capacity level description" into main

1 files changed, 49 insertions, 35 deletions

diff --git a/core/java/android/os/BatteryManager.java b/core/java/android/os/BatteryManager.java
index 8b267bf28c7e..b63ad5f0148e 100644
--- a/core/java/android/os/BatteryManager.java
+++ b/core/java/android/os/BatteryManager.java
@@ -167,76 +167,90 @@ public class BatteryManager {
     public static final String EXTRA_CHARGING_STATUS = "android.os.extra.CHARGING_STATUS";
 
     /**
-     * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}:
-     * Int value representing the battery's capacity level. These constants are key indicators of
-     * battery status and system capabilities, guiding power management decisions for both the
-     * system and apps:
-     * {@link #BATTERY_CAPACITY_LEVEL_UNSUPPORTED}: Feature not supported on this device.
-     * {@link #BATTERY_CAPACITY_LEVEL_UNKNOWN}: Battery status is unavailable or uninitialized.
-     * {@link #BATTERY_CAPACITY_LEVEL_CRITICAL}: Battery is critically low and the Android
-     * framework has been notified to schedule a shutdown by this value
-     * {@link #BATTERY_CAPACITY_LEVEL_LOW}: Android framework must limit background jobs to
-     * avoid impacting charging speed
-     * {@link #BATTERY_CAPACITY_LEVEL_NORMAL}: Battery level and charging rates are normal,
-     * battery temperature is within normal range and adapter power is enough to charge the
-     * battery at an acceptable rate. Android framework can run light background tasks without
-     * affecting charging performance severely.
-     * {@link #BATTERY_CAPACITY_LEVEL_HIGH}: Battery level is high, battery temperature is
-     * within normal range and adapter power is enough to charge the battery at an acceptable
-     * rate while running background loads. Android framework can run background tasks without
-     * affecting charging or battery performance.
-     * {@link #BATTERY_CAPACITY_LEVEL_FULL}: The battery is full, battery temperature is
-     * within normal range and adapter power is enough to sustain running background loads.
-     * Android framework can run background tasks without affecting the battery level or
-     * battery performance.
-     */
-
-    @FlaggedApi(FLAG_BATTERY_PART_STATUS_API)
-    public static final String EXTRA_CAPACITY_LEVEL = "android.os.extra.CAPACITY_LEVEL";
-
-    /**
-     * Battery capacity level is unsupported. @see EXTRA_CAPACITY_LEVEL
+     * Battery capacity level is unsupported.
+     *
+     * @see #EXTRA_CAPACITY_LEVEL
      */
     @FlaggedApi(FLAG_BATTERY_PART_STATUS_API)
     public static final int BATTERY_CAPACITY_LEVEL_UNSUPPORTED = -1;
 
     /**
-     * Battery capacity level is unknown. @see EXTRA_CAPACITY_LEVEL
+     * Battery capacity level is unknown.
+     *
+     * @see #EXTRA_CAPACITY_LEVEL
      */
     @FlaggedApi(FLAG_BATTERY_PART_STATUS_API)
     public static final int BATTERY_CAPACITY_LEVEL_UNKNOWN = 0;
 
     /**
-     * Battery capacity level is critical. @see EXTRA_CAPACITY_LEVEL
+     * Battery capacity level is critical. The Android framework has been notified to schedule
+     * a shutdown by this value.
+     *
+     * @see #EXTRA_CAPACITY_LEVEL
      */
     @FlaggedApi(FLAG_BATTERY_PART_STATUS_API)
     public static final int BATTERY_CAPACITY_LEVEL_CRITICAL = 1;
 
     /**
-     * Battery capacity level is low. @see EXTRA_CAPACITY_LEVEL
+     * Battery capacity level is low. The Android framework must limit background jobs to avoid
+     * impacting charging speed.
+     *
+     * @see #EXTRA_CAPACITY_LEVEL
      */
     @FlaggedApi(FLAG_BATTERY_PART_STATUS_API)
     public static final int BATTERY_CAPACITY_LEVEL_LOW = 2;
 
     /**
-     * Battery capacity level is normal. @see EXTRA_CAPACITY_LEVEL
+     * Battery capacity level is normal. Battery level and charging rates are normal, battery
+     * temperature is within the normal range, and adapter power is enough to charge the battery
+     * at an acceptable rate. The Android framework can run light background tasks without
+     * affecting charging performance severely.
+     *
+     * @see #EXTRA_CAPACITY_LEVEL
      */
     @FlaggedApi(FLAG_BATTERY_PART_STATUS_API)
     public static final int BATTERY_CAPACITY_LEVEL_NORMAL = 3;
 
     /**
-     * Battery capacity level is high. @see EXTRA_CAPACITY_LEVEL
+     * Battery capacity level is high. Battery level is high, battery temperature is within the
+     * normal range, and adapter power is enough to charge the battery at an acceptable rate
+     * while running background loads. The Android framework can run background tasks without
+     * affecting charging or battery performance.
+     *
+     * @see #EXTRA_CAPACITY_LEVEL
      */
     @FlaggedApi(FLAG_BATTERY_PART_STATUS_API)
     public static final int BATTERY_CAPACITY_LEVEL_HIGH = 4;
 
     /**
-     * Battery capacity level is full. @see EXTRA_CAPACITY_LEVEL
+     * Battery capacity level is full. The battery is full, the battery temperature is within the
+     * normal range, and adapter power is enough to sustain running background loads. The Android
+     * framework can run background tasks without affecting the battery level or battery
+     * performance.
+     *
+     * @see #EXTRA_CAPACITY_LEVEL
      */
     @FlaggedApi(FLAG_BATTERY_PART_STATUS_API)
     public static final int BATTERY_CAPACITY_LEVEL_FULL = 5;
 
     /**
+     * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}:
+     * Int value representing the battery's capacity level. These constants are key indicators of
+     * battery status and system capabilities, guiding power management decisions for both the
+     * system and apps.
+     *
+     * @see #BATTERY_CAPACITY_LEVEL_UNSUPPORTED
+     * @see #BATTERY_CAPACITY_LEVEL_UNKNOWN
+     * @see #BATTERY_CAPACITY_LEVEL_CRITICAL
+     * @see #BATTERY_CAPACITY_LEVEL_LOW
+     * @see #BATTERY_CAPACITY_LEVEL_NORMAL
+     * @see #BATTERY_CAPACITY_LEVEL_HIGH
+     * @see #BATTERY_CAPACITY_LEVEL_FULL
+     */
+    @FlaggedApi(FLAG_BATTERY_PART_STATUS_API)
+    public static final String EXTRA_CAPACITY_LEVEL = "android.os.extra.CAPACITY_LEVEL";
+
+    /**
      * Extra for {@link android.content.Intent#ACTION_BATTERY_LEVEL_CHANGED}:
      * Contains list of Bundles representing battery events
      * @hide