📝 Add docstrings to mqtt

Docstrings generation was requested by @natekspencer.

* https://github.com/natekspencer/hacs-oasis_mini/pull/98#issuecomment-3568450288

The following files were modified:

* `custom_components/oasis_mini/__init__.py`
* `custom_components/oasis_mini/binary_sensor.py`
* `custom_components/oasis_mini/button.py`
* `custom_components/oasis_mini/config_flow.py`
* `custom_components/oasis_mini/coordinator.py`
* `custom_components/oasis_mini/entity.py`
* `custom_components/oasis_mini/helpers.py`
* `custom_components/oasis_mini/image.py`
* `custom_components/oasis_mini/light.py`
* `custom_components/oasis_mini/media_player.py`
* `custom_components/oasis_mini/number.py`
* `custom_components/oasis_mini/pyoasiscontrol/clients/cloud_client.py`
* `custom_components/oasis_mini/pyoasiscontrol/clients/http_client.py`
* `custom_components/oasis_mini/pyoasiscontrol/clients/mqtt_client.py`
* `custom_components/oasis_mini/pyoasiscontrol/clients/transport.py`
* `custom_components/oasis_mini/pyoasiscontrol/device.py`
* `custom_components/oasis_mini/pyoasiscontrol/utils.py`
* `custom_components/oasis_mini/select.py`
* `custom_components/oasis_mini/sensor.py`
* `custom_components/oasis_mini/switch.py`
* `custom_components/oasis_mini/update.py`
* `update_tracks.py`

custom_components/oasis_mini/__init__.py

@@ -44,13 +44,31 @@ def setup_platform_from_coordinator(
     make_entities: Callable[[OasisDevice], Iterable[OasisDeviceEntity]],
     update_before_add: bool = False,
 ) -> None:
-    """Generic pattern: add entities per device, including newly discovered ones."""
+    """
+    Populate entities for devices managed by the coordinator and add entities for any devices discovered later.
+    
+    This registers a listener on the coordinator to detect newly discovered devices by serial number and calls `make_entities` to construct entity objects for those devices, passing them to `async_add_entities`. The initial device set is processed immediately; subsequent discoveries are handled via the coordinator listener.
+    
+    Parameters:
+        entry: Config entry containing the coordinator in its `runtime_data`.
+        async_add_entities: Home Assistant callback to add entities to the platform.
+        make_entities: Callable that accepts an iterable of `OasisDevice` objects and returns an iterable of `OasisDeviceEntity` instances to add.
+        update_before_add: If true, entities will be updated before being added.
+    """
     coordinator = entry.runtime_data
 
     known_serials: set[str] = set()
 
     @callback
     def _check_devices() -> None:
+        """
+        Detect newly discovered Oasis devices from the coordinator and register their entities.
+        
+        Scans the coordinator's current device list for devices with a serial number that has not
+        been seen before. For any newly discovered devices, creates entity instances via
+        make_entities and adds them to Home Assistant using async_add_entities with the
+        update_before_add flag. Does not return a value.
+        """
         devices = coordinator.data or []
         new_devices: list[OasisDevice] = []
 
@@ -75,7 +93,12 @@ def setup_platform_from_coordinator(
 
 
 async def async_setup_entry(hass: HomeAssistant, entry: OasisDeviceConfigEntry) -> bool:
-    """Set up Oasis devices from a config entry."""
+    """
+    Initialize Oasis cloud and MQTT integration for a config entry, create and refresh the device coordinator, register update listeners for discovered devices, forward platform setup, and update the entry's metadata as needed.
+    
+    Returns:
+        True if the config entry was set up successfully.
+    """
     cloud_client = create_client(hass, entry.data)
     try:
         user = await cloud_client.async_get_user()
@@ -101,6 +124,11 @@ async def async_setup_entry(hass: HomeAssistant, entry: OasisDeviceConfigEntry)
     entry.runtime_data = coordinator
 
     def _on_oasis_update() -> None:
+        """
+        Update the coordinator's last-updated timestamp and notify its listeners.
+        
+        Sets the coordinator's last_updated to the current time and triggers its update listeners so dependent entities and tasks refresh.
+        """
         coordinator.last_updated = dt_util.now()
         coordinator.async_update_listeners()
 
@@ -115,7 +143,14 @@ async def async_setup_entry(hass: HomeAssistant, entry: OasisDeviceConfigEntry)
 async def async_unload_entry(
     hass: HomeAssistant, entry: OasisDeviceConfigEntry
 ) -> bool:
-    """Unload a config entry."""
+    """
+    Cleanly unload an Oasis device config entry.
+    
+    Closes the MQTT and cloud clients stored on the entry and unloads all supported platforms.
+    
+    Returns:
+        `True` if all platforms were unloaded successfully, `False` otherwise.
+    """
     mqtt_client = entry.runtime_data.mqtt_client
     await mqtt_client.async_close()
 
@@ -128,7 +163,11 @@ async def async_unload_entry(
 async def async_remove_entry(
     hass: HomeAssistant, entry: OasisDeviceConfigEntry
 ) -> None:
-    """Handle removal of an entry."""
+    """
+    Perform logout and cleanup for the cloud client associated with the config entry.
+    
+    Attempts to call the cloud client's logout method and logs any exception encountered, then ensures the client is closed.
+    """
     cloud_client = create_client(hass, entry.data)
     try:
         await cloud_client.async_logout()
@@ -138,7 +177,20 @@ async def async_remove_entry(
 
 
 async def async_migrate_entry(hass: HomeAssistant, entry: OasisDeviceConfigEntry):
-    """Migrate old entry."""
+    """
+    Migrate an Oasis config entry to the current schema (minor version 3).
+    
+    Performs in-place migrations for older entries:
+    - Renames select entity unique IDs ending with `-playlist` to `-queue`.
+    - When migrating to the auth-required schema, moves relevant options into entry data and clears options.
+    - Updates the config entry's data, options, minor_version, title (from CONF_EMAIL or "Oasis Control"), unique_id, and version.
+    
+    Parameters:
+        entry: The config entry to migrate.
+    
+    Returns:
+        `True` if migration succeeded, `False` if migration could not be performed (e.g., entry.version is greater than supported).
+    """
     _LOGGER.debug(
         "Migrating configuration from version %s.%s", entry.version, entry.minor_version
     )
@@ -157,7 +209,15 @@ async def async_migrate_entry(hass: HomeAssistant, entry: OasisDeviceConfigEntry
             def migrate_unique_id(
                 entity_entry: er.RegistryEntry,
             ) -> dict[str, Any] | None:
-                """Migrate the playlist unique ID to queue."""
+                """
+                Update a registry entry's unique_id suffix from "-playlist" to "-queue" when applicable.
+                
+                Parameters:
+                    entity_entry (er.RegistryEntry): Registry entry to inspect.
+                
+                Returns:
+                    dict[str, Any] | None: A mapping {"new_unique_id": <new id>} if the entry is in the "select" domain and its unique_id ends with "-playlist"; otherwise `None`.
+                """
                 if entity_entry.domain == "select" and entity_entry.unique_id.endswith(
                     "-playlist"
                 ):
@@ -194,10 +254,19 @@ async def async_migrate_entry(hass: HomeAssistant, entry: OasisDeviceConfigEntry
 async def async_remove_config_entry_device(
     hass: HomeAssistant, config_entry: OasisDeviceConfigEntry, device_entry: DeviceEntry
 ) -> bool:
-    """Remove a config entry from a device."""
+    """
+    Determine whether the config entry is no longer associated with the given device.
+    
+    Parameters:
+        config_entry (OasisDeviceConfigEntry): The config entry whose runtime data contains device serial numbers.
+        device_entry (DeviceEntry): The device registry entry to check for matching identifiers.
+    
+    Returns:
+        bool: `true` if none of the device's identifiers match serial numbers present in the config entry's runtime data, `false` otherwise.
+    """
     current_serials = {d.serial_number for d in (config_entry.runtime_data.data or [])}
     return not any(
         identifier
         for identifier in device_entry.identifiers
         if identifier[0] == DOMAIN and identifier[1] in current_serials
-    )
+    )