Add docstring to Sensor enums (#79983)

* Add docstring to Sensor enums

* Adjust MONETARY docstring

homeassistant/components/sensor/__init__.py

@@ -85,116 +85,243 @@ SCAN_INTERVAL: Final = timedelta(seconds=30)
 class SensorDeviceClass(StrEnum):
     """Device class for sensors."""
 
-    # apparent power (VA)
     APPARENT_POWER = "apparent_power"
+    """Apparent power.
+
+    Unit of measurement: `VA`
+    """
 
-    # Air Quality Index
     AQI = "aqi"
+    """Air Quality Index.
+
+    Unit of measurement: `None`
+    """
 
-    # % of battery that is left
     BATTERY = "battery"
+    """Percentage of battery that is left.
+
+    Unit of measurement: `%`
+    """
 
-    # ppm (parts per million) Carbon Monoxide gas concentration
     CO = "carbon_monoxide"
+    """Carbon Monoxide gas concentration.
+
+    Unit of measurement: `ppm` (parts per million)
+    """
 
-    # ppm (parts per million) Carbon Dioxide gas concentration
     CO2 = "carbon_dioxide"
+    """Carbon Dioxide gas concentration.
+
+    Unit of measurement: `ppm` (parts per million)
+    """
 
-    # current (A)
     CURRENT = "current"
+    """Current.
+
+    Unit of measurement: `A`
+    """
 
-    # date (ISO8601)
     DATE = "date"
+    """Date.
+
+    Unit of measurement: `None`
+
+    ISO8601 format: https://en.wikipedia.org/wiki/ISO_8601
+    """
 
-    # distance (LENGTH_*)
     DISTANCE = "distance"
+    """Generic distance.
+
+    Unit of measurement: `LENGTH_*` units
+    - SI /metric: `mm`, `cm`, `m`, `km`
+    - USCS / imperial: `in`, `ft`, `yd`, `mi`
+    """
 
-    # fixed duration (TIME_DAYS, TIME_HOURS, TIME_MINUTES, TIME_SECONDS)
     DURATION = "duration"
+    """Fixed duration.
+
+    Unit of measurement: `d`, `h`, `min`, `s`
+    """
 
-    # energy (Wh, kWh, MWh)
     ENERGY = "energy"
+    """Energy.
+
+    Unit of measurement: `Wh`, `kWh`, `MWh`
+    """
 
-    # frequency (Hz, kHz, MHz, GHz)
     FREQUENCY = "frequency"
+    """Frequency.
+
+    Unit of measurement: `Hz`, `kHz`, `MHz`, `GHz`
+    """
 
-    # gas (m³ or ft³)
     GAS = "gas"
+    """Gas.
+
+    Unit of measurement: `m³`, `ft³`
+    """
 
-    # Relative humidity (%)
     HUMIDITY = "humidity"
+    """Relative humidity.
+
+    Unit of measurement: `%`
+    """
 
-    # current light level (lx/lm)
     ILLUMINANCE = "illuminance"
+    """Illuminance.
+
+    Unit of measurement: `lx`, `lm`
+    """
 
-    # moisture (%)
     MOISTURE = "moisture"
+    """Moisture.
+
+    Unit of measurement: `%`
+    """
 
-    # Amount of money (currency)
     MONETARY = "monetary"
+    """Amount of money.
+
+    Unit of measurement: ISO4217 currency code
+
+    See https://en.wikipedia.org/wiki/ISO_4217#Active_codes for active codes
+    """
 
-    # Amount of NO2 (µg/m³)
     NITROGEN_DIOXIDE = "nitrogen_dioxide"
+    """Amount of NO2.
+
+    Unit of measurement: `µg/m³`
+    """
 
-    # Amount of NO (µg/m³)
     NITROGEN_MONOXIDE = "nitrogen_monoxide"
+    """Amount of NO.
+
+    Unit of measurement: `µg/m³`
+    """
 
-    # Amount of N2O  (µg/m³)
     NITROUS_OXIDE = "nitrous_oxide"
+    """Amount of N2O.
+
+    Unit of measurement: `µg/m³`
+    """
 
-    # Amount of O3 (µg/m³)
     OZONE = "ozone"
+    """Amount of O3.
+
+    Unit of measurement: `µg/m³`
+    """
 
-    # Particulate matter <= 0.1 μm (µg/m³)
     PM1 = "pm1"
+    """Particulate matter <= 0.1 μm.
+
+    Unit of measurement: `µg/m³`
+    """
 
-    # Particulate matter <= 10 μm (µg/m³)
     PM10 = "pm10"
+    """Particulate matter <= 10 μm.
+
+    Unit of measurement: `µg/m³`
+    """
 
-    # Particulate matter <= 2.5 μm (µg/m³)
     PM25 = "pm25"
+    """Particulate matter <= 2.5 μm.
+
+    Unit of measurement: `µg/m³`
+    """
 
-    # power factor (%)
     POWER_FACTOR = "power_factor"
+    """Power factor.
+
+    Unit of measurement: `%`
+    """
 
-    # power (W/kW)
     POWER = "power"
+    """Power.
+
+    Unit of measurement: `W`, `kW`
+    """
 
-    # pressure (hPa/mbar)
     PRESSURE = "pressure"
+    """Pressure.
+
+    Unit of measurement:
+    - `mbar`, `cbar`, `bar`
+    - `Pa`, `hPa`, `kPa`
+    - `inHg`
+    - `psi`
+    """
 
-    # reactive power (var)
     REACTIVE_POWER = "reactive_power"
+    """Reactive power.
+
+    Unit of measurement: `var`
+    """
 
-    # signal strength (dB/dBm)
     SIGNAL_STRENGTH = "signal_strength"
+    """Signal strength.
+
+    Unit of measurement: `dB`, `dBm`
+    """
 
-    # speed (SPEED_*)
     SPEED = "speed"
+    """Generic speed.
+
+    Unit of measurement: `SPEED_*` units
+    - SI /metric: `mm/d`, `mm/h`, `m/s`, `km/h`
+    - USCS / imperial: `in/d`, `in/h`, `ft/s`, `mph`
+    - Nautical: `kn`
+    """
 
-    # Amount of SO2 (µg/m³)
     SULPHUR_DIOXIDE = "sulphur_dioxide"
+    """Amount of SO2.
+
+    Unit of measurement: `µg/m³`
+    """
 
-    # temperature (C/F)
     TEMPERATURE = "temperature"
+    """Temperature.
+
+    Unit of measurement: `°C`, `°F`
+    """
 
-    # timestamp (ISO8601)
     TIMESTAMP = "timestamp"
+    """Timestamp.
+
+    Unit of measurement: `None`
+
+    ISO8601 format: https://en.wikipedia.org/wiki/ISO_8601
+    """
 
-    # Amount of VOC (µg/m³)
     VOLATILE_ORGANIC_COMPOUNDS = "volatile_organic_compounds"
+    """Amount of VOC.
+
+    Unit of measurement: `µg/m³`
+    """
 
-    # voltage (V)
     VOLTAGE = "voltage"
+    """Voltage.
+
+    Unit of measurement: `V`
+    """
 
-    # volume (VOLUME_*)
     VOLUME = "volume"
+    """Generic volume.
+
+    Unit of measurement: `VOLUME_*` units
+    - SI / metric: `mL`, `L`, `m³`
+    - USCS / imperial: `fl. oz.`, `gal`, `ft³` (warning: volumes expressed in
+    USCS/imperial units are currently assumed to be US volumes)
+    """
 
     # weight/mass (g, kg, mg, µg, oz, lb)
     WEIGHT = "weight"
-    """Represent a measurement of an object's mass.
+    """Generic weight, represents a measurement of an object's mass.
 
     Weight is used instead of mass to fit with every day language.
+
+    Unit of measurement: `MASS_*` units
+    - SI / metric: `µg`, `mg`, `g`, `kg`
+    - USCS / imperial: `oz`, `lb`
     """
 
 
@@ -208,14 +335,18 @@ DEVICE_CLASSES: Final[list[str]] = [cls.value for cls in SensorDeviceClass]
 class SensorStateClass(StrEnum):
     """State class for sensors."""
 
-    # The state represents a measurement in present time
     MEASUREMENT = "measurement"
+    """The state represents a measurement in present time."""
 
-    # The state represents a total amount, e.g. net energy consumption
     TOTAL = "total"
+    """The state represents a total amount.
+
+    For example: net energy consumption"""
 
-    # The state represents a monotonically increasing total, e.g. an amount of consumed gas
     TOTAL_INCREASING = "total_increasing"
+    """The state represents a monotonically increasing total.
+
+    For example: an amount of consumed gas"""
 
 
 STATE_CLASSES_SCHEMA: Final = vol.All(vol.Lower, vol.Coerce(SensorStateClass))