Fix inconsistencies in VehicleArea HAL documentation

Remove references of area types and use more consistent language.
Use same documentation across AIDL and HIDL definitions.

Bug: 259987652
Test: presubmit
Change-Id: I4da6ff23fd221698c9fbe9c9f817f51959a49a79

automotive/vehicle/2.0/types.hal

@@ -57,46 +57,25 @@ enum VehiclePropertyType : int32_t {
 };
 
 /**
- * Vehicle Areas
+ * List of different supported area types for vehicle properties.
  * Used to construct property IDs in the VehicleProperty enum.
  *
- * Some properties may be associated with particular vehicle areas. For
+ * Some properties may be associated with particular areas in the vehicle. For example,
- * example, VehicleProperty:DOOR_LOCK property must be associated with
+ * VehicleProperty#DOOR_LOCK property must be associated with a particular door, thus this property
- * particular door, thus this property must be marked with
+ * must be of the VehicleArea#DOOR area type.
- * VehicleArea:DOOR flag.
  *
- * Other properties may not be associated with particular vehicle area.
+ * Other properties may not be associated with a particular area in the vehicle. These kinds of
- * These kinds of properties must have VehicleArea:GLOBAL flag.
+ * properties must be of the VehicleArea#GLOBAL area type.
  *
- * [Definition] Area: An area represents a unique element of an AreaType.
+ * Note: This is not the same as areaId used in VehicleAreaConfig. E.g. for a global property, the
- *   For instance, if AreaType is WINDOW, then an area may be FRONT_WINDSHIELD.
+ * property ID is of the VehicleArea#GLOBAL area type, however, the area ID must be 0.
- *
+ */
- * [Definition] AreaID: An AreaID is a combination of one or more areas,
+// A better name would be VehicleAreaType
- *   and is represented using a bitmask of Area enums. Different AreaTypes may
- *   not be mixed in a single AreaID. For instance, a window area cannot be
- *   combined with a seat area in an AreaID.
- *
- * Rules for mapping a zoned property to AreaIDs:
- *  - A property must be mapped to an array of AreaIDs that are impacted when
- *    the property value changes.
- *  - Each element in the array must represent an AreaID, in which the
- *    property value can only be changed together in all the areas within
- *    the AreaID and never independently. That is, when the property value
- *    changes in one of the areas in an AreaID in the array, then it must
- *    automatically change in all other areas in the AreaID.
- *  - The property value must be independently controllable in any two
- *    different AreaIDs in the array.
- *  - An area must only appear once in the array of AreaIDs. That is, an
- *    area must only be part of a single AreaID in the array.
- *
- * [Definition] Global Property: A property that applies to the entire car
- *   and is not associated with a specific area. For example, FUEL_LEVEL,
- *   HVAC_STEERING_WHEEL_HEAT.
- *
- * Rules for mapping a global property to AreaIDs:
- *  - A global property must not be mapped to AreaIDs.
-*/
 enum VehicleArea : int32_t {
+    /**
+     * A global property is a property that applies to the entire vehicle and is not associated with
+     * a specific area. For example, FUEL_LEVEL, HVAC_STEERING_WHEEL_HEAT are global properties.
+     */
     GLOBAL      = 0x01000000,
     /** WINDOW maps to enum VehicleAreaWindow */
     WINDOW      = 0x03000000,

automotive/vehicle/aidl/android/hardware/automotive/vehicle/VehicleAreaConfig.aidl

@@ -20,7 +20,7 @@ package android.hardware.automotive.vehicle;
 @JavaDerive(equals=true, toString=true)
 parcelable VehicleAreaConfig {
     /**
-     * Area id is ignored for VehiclePropertyGroup:GLOBAL properties.
+     * Area id is always 0 for VehicleArea#GLOBAL properties.
      */
     int areaId;
 

automotive/vehicle/aidl/android/hardware/automotive/vehicle/VehiclePropConfig.aidl

@@ -37,7 +37,25 @@ parcelable VehiclePropConfig {
     VehiclePropertyChangeMode changeMode = VehiclePropertyChangeMode.STATIC;
 
     /**
-     * Contains per-area configuration.
+     * Contains per-areaId configuration.
+     *
+     * [Definition] area: An area represents a unique element of a VehicleArea. For instance, if the
+     *   VehicleArea is WINDOW, then an example area is FRONT_WINDSHIELD.
+     *
+     * [Definition] area ID: An area ID is a combination of one or more areas, and is created by
+     *   bitwise "OR"ing the areas together. Areas from different VehicleArea values may not be
+     *   mixed in a single area ID. For example, a VehicleAreaWindow area cannot be combined with a
+     *   VehicleAreaSeat area in an area ID.
+     *
+     * For VehicleArea#GLOBAL properties, they must map only to a single area ID of 0.
+     *
+     * Rules for mapping a non VehicleArea#GLOBAL property to area IDs:
+     *  - A property must be mapped to a set of area IDs that are impacted when the property value
+     *    changes.
+     *  - An area cannot be part of multiple area IDs, it must only be part of a single area ID.
+     *  - When the property value changes in one of the areas in an area ID, then it must
+     *    automatically change in all other areas in the area ID.
+     *  - The property value must be independently controllable in any two different area IDs.
      */
     VehicleAreaConfig[] areaConfigs;
 

automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehicleArea.aidl

@@ -16,9 +16,28 @@
 
 package android.hardware.automotive.vehicle;
 
+/**
+ * List of different supported area types for vehicle properties.
+ * Used to construct property IDs in the VehicleProperty enum.
+ *
+ * Some properties may be associated with particular areas in the vehicle. For example,
+ * VehicleProperty#DOOR_LOCK property must be associated with a particular door, thus this property
+ * must be of the VehicleArea#DOOR area type.
+ *
+ * Other properties may not be associated with a particular area in the vehicle. These kinds of
+ * properties must be of the VehicleArea#GLOBAL area type.
+ *
+ * Note: This is not the same as areaId used in VehicleAreaConfig. E.g. for a global property, the
+ * property ID is of the VehicleArea#GLOBAL area type, however, the area ID must be 0.
+ */
 @VintfStability
 @Backing(type="int")
+// A better name would be VehicleAreaType
 enum VehicleArea {
+    /**
+     * A global property is a property that applies to the entire vehicle and is not associated with
+     * a specific area. For example, FUEL_LEVEL, HVAC_STEERING_WHEEL_HEAT are global properties.
+     */
     GLOBAL = 0x01000000,
     /** WINDOW maps to enum VehicleAreaWindow */
     WINDOW = 0x03000000,

current.txt

@@ -937,5 +937,6 @@ a2fbd9747fbb9ceb8c1090b5a24138312246502d5af0654a8c2b603a9bf521fc android.hardwar
 889b59e3e7a59afa67bf19882a44f51a2f9e43b6556ec52baa9ec3efd1ef7fbe android.hardware.camera.device@3.2::types
 db37a1c757e2e69b1ec9c75a981a6987bd87a131d92ab6acc00e04d19f374281 android.hardware.automotive.vehicle@2.0::types
 997017f581406fca1675d2f612f7ccd73f0d04eadd54bf6212e6cf5971d0872d android.hardware.automotive.vehicle@2.0::types
+06983ffe6d75e90a22503a6d9fd14417f983a36bb060a80ad5915240d69b8a40 android.hardware.automotive.vehicle@2.0::types
 
 # There will be no more HIDL HALs. Use AIDL instead.