BatteryManager: update capacity level description
Bug: 376119147
Change-Id: Id34f338b50fad9c04aaf59627132db030a71f6d4
Signed-off-by: Jenny Ho <hsiufangho@google.com>
diff --git a/core/java/android/os/BatteryManager.java b/core/java/android/os/BatteryManager.java
index 8b267bf..b63ad5f 100644
--- a/core/java/android/os/BatteryManager.java
+++ b/core/java/android/os/BatteryManager.java
@@ -167,76 +167,90 @@
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