From 68175631b6fdd55b95afafeff7b030d9a2610f21 Mon Sep 17 00:00:00 2001
From: Aaqib Ismail <aaqibismail@google.com>
Date: Tue, 14 Feb 2023 13:52:01 -0800
Subject: [PATCH] Add missing documentation in HAL for enum states

This change for WindshieldWipersState, VehicleOilLevel, and
TrailerState aligns the documentation in the HAL with the API level.

Bug: 269329431
Test: presubmit
Change-Id: I115ac9a6f03c051b0de526e60a44dca41220533f
---
 .../automotive/vehicle/TrailerState.aidl       | 18 ++++++++++++++++--
 .../automotive/vehicle/VehicleOilLevel.aidl    | 17 ++++++++++++++++-
 .../vehicle/WindshieldWipersState.aidl         |  7 ++++++-
 3 files changed, 38 insertions(+), 4 deletions(-)

diff --git a/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/TrailerState.aidl b/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/TrailerState.aidl
index fd420626d6..ef653746c2 100644
--- a/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/TrailerState.aidl
+++ b/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/TrailerState.aidl
@@ -17,14 +17,28 @@
 package android.hardware.automotive.vehicle;
 
 /**
- * Used by the trailer present property to enumerate the current state
- * of the trailer.
+ * Used to enumerate the current state of VehicleProperty#TRAILER_PRESENT.
  */
 @VintfStability
 @Backing(type="int")
 enum TrailerState {
+    /**
+     * This state is used as an alternative for any TrailerState value that is not defined in the
+     * platform. Ideally, implementations of VehicleProperty#TRAILER_PRESENT should not use this
+     * state. The framework can use this field to remain backwards compatible if TrailerState is
+     * extended to include additional states.
+     */
     UNKNOWN = 0,
+    /**
+     * A trailer is not attached to the vehicle.
+     */
     NOT_PRESENT = 1,
+    /**
+     * A trailer is attached to the vehicle.
+     */
     PRESENT = 2,
+    /**
+     * The state of the trailer is not available due to an error.
+     */
     ERROR = 3,
 }
diff --git a/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehicleOilLevel.aidl b/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehicleOilLevel.aidl
index bf3c858c55..3c722bad8e 100644
--- a/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehicleOilLevel.aidl
+++ b/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehicleOilLevel.aidl
@@ -16,15 +16,30 @@
 
 package android.hardware.automotive.vehicle;
 
+/**
+ * Used to enumerate the current level of VehicleProperty#ENGINE_OIL_LEVEL.
+ */
 @VintfStability
 @Backing(type="int")
 enum VehicleOilLevel {
     /**
-     * Oil level values
+     * The oil level of the engine is critically low, so the vehicle may be unsafe to drive.
      */
     CRITICALLY_LOW = 0,
+    /**
+     * The oil level of the engine is low and needs to be replaced.
+     */
     LOW = 1,
+    /**
+     * The oil level of the engine is normal for the vehicle.
+     */
     NORMAL = 2,
+    /**
+     * The oil level of the engine is high, so the vehicle may be unsafe to drive.
+     */
     HIGH = 3,
+    /**
+     * This value represents an error when retrieving the oil level of the engine.
+     */
     ERROR = 4,
 }
diff --git a/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/WindshieldWipersState.aidl b/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/WindshieldWipersState.aidl
index 5873065261..820fcc8659 100644
--- a/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/WindshieldWipersState.aidl
+++ b/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/WindshieldWipersState.aidl
@@ -30,9 +30,14 @@ enum WindshieldWipersState {
      * WindshieldWipersState is extended to include additional states.
      */
     OTHER = 0,
+    /**
+     * This state indicates the windshield wipers are currently off. If
+     * VehicleProperty#WINDSHIELD_WIPERS_SWITCH is implemented, then it may be set to any of the
+     * following modes: OFF or AUTO.
+     */
     OFF = 1,
     /**
-     * This state indicates windshield wipers are currently on. If
+     * This state indicates the windshield wipers are currently on. If
      * VehicleProperty#WINDSHIELD_WIPERS_SWITCH is implemented, then it may be set to any of the
      * following modes: MIST, INTERMITTENT_LEVEL_*, CONTINUOUS_LEVEL_*, or AUTO.
      */