docs: Document metadata keys in field_metadata and is_field_supported

Author: allenporter

roborock/data/containers.py

@@ -61,10 +61,15 @@ def _attr_repr(obj: Any) -> str:
 
 
 def field_metadata(**kwargs):
-    """Decorator to attach metadata to a function or property.
+    """Decorator to attach capability check metadata to a property.
 
     This attaches a `_field_metadata` dictionary to the underlying getter function,
     which is then preserved when decorated with `@property`.
+
+    Supported metadata keys:
+    - `feature` (str): Name of a capability property on `DeviceFeaturesTrait`.
+    - `dock_feature` (str): Name of a capability property on `RoborockDockFeatures`.
+    - `dps` (str/int): RoborockDataProtocol ID to check against supported schema IDs.
     """
 
     def decorator(func):

roborock/devices/traits/v1/device_features.py

@@ -72,9 +72,13 @@ def __init__(self, product: HomeDataProduct, device_cache: DeviceCache) -> None:
     def is_field_supported(self, cls: type[RoborockBase], field_name: FieldNameBase) -> bool:
         """Determines if the specified field is supported by this device.
 
-        We use the `dps` dataclass field metadata to get the `RoborockDataProtocol`
-        integer ID and check it against the set of supported schema IDs for the
-        device returned in the product information.
+        We inspect the metadata defined for the field (either via dataclass field metadata
+        or the `@field_metadata` decorator on properties). Supported checks include:
+
+        - `feature`: Maps to a boolean capability property on `DeviceFeatures` / `DeviceFeaturesTrait`
+          (e.g. `is_support_water_mode`).
+        - `dock_feature`: Maps to a boolean capability property on `RoborockDockFeatures` (e.g. `is_washable`).
+        - `dps`: Maps to a `RoborockDataProtocol` ID checked against the product's supported schema IDs.
         """
         if self.dock_features is None:
             raise ValueError("DeviceFeaturesTrait was invoked but was not fully initialized")