📝 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/select.py

@@ -22,7 +22,16 @@ AUTOPLAY_MAP_LIST = list(AUTOPLAY_MAP)
 
 
 def playlists_update_handler(entity: OasisDeviceSelectEntity) -> None:
-    """Handle playlists updates."""
+    """
+    Update the playlists select options and current option from the device's cloud playlists.
+    
+    Iterates the device's cloud playlists to build a display list of playlist names (appending " (N)" for duplicate names)
+    and sets the entity's options to that list. If the device's current playlist matches a playlist's pattern IDs,
+    sets the entity's current option to that playlist's display name; otherwise leaves it None.
+    
+    Parameters:
+        entity (OasisDeviceSelectEntity): The select entity to update.
+    """
     # pylint: disable=protected-access
     device = entity.device
     counts = defaultdict(int)
@@ -41,7 +50,14 @@ def playlists_update_handler(entity: OasisDeviceSelectEntity) -> None:
 
 
 def queue_update_handler(entity: OasisDeviceSelectEntity) -> None:
-    """Handle queue updates."""
+    """
+    Update the select options and current selection for the device's playback queue.
+    
+    Populate the entity's options from the device's current playlist and playlist details, disambiguating duplicate track names by appending a counter (e.g., "Title (2)"). Set the entity's current option to the track at device.playlist_index (or None if the queue is empty).
+    
+    Parameters:
+        entity (OasisDeviceSelectEntity): The select entity whose options and current option will be updated.
+    """
     # pylint: disable=protected-access
     device = entity.device
     counts = defaultdict(int)
@@ -70,9 +86,27 @@ async def async_setup_entry(
     entry: OasisDeviceConfigEntry,
     async_add_entities: AddEntitiesCallback,
 ) -> None:
-    """Set up Oasis device select using config entry."""
+    """
+    Set up select entities for each Oasis device from a config entry.
+    
+    Creates OasisDeviceSelectEntity instances for every device and descriptor and registers them with Home Assistant via the platform setup.
+    
+    Parameters:
+        hass: Home Assistant instance.
+        entry: Oasis device config entry used to locate coordinator and runtime data.
+        async_add_entities: Callback to add created entities to Home Assistant.
+    """
 
     def make_entities(new_devices: list[OasisDevice]):
+        """
+        Create select entity instances for each provided Oasis device.
+        
+        Parameters:
+            new_devices (list[OasisDevice]): Devices to create select entities for.
+        
+        Returns:
+            list[OasisDeviceSelectEntity]: A flat list of OasisDeviceSelectEntity objects created for every combination of device and descriptor.
+        """
         return [
             OasisDeviceSelectEntity(entry.runtime_data, device, descriptor)
             for device in new_devices
@@ -133,17 +167,37 @@ class OasisDeviceSelectEntity(OasisDeviceEntity, SelectEntity):
         device: OasisDevice,
         description: EntityDescription,
     ) -> None:
-        """Construct an Oasis device select entity."""
+        """
+        Initialize the Oasis device select entity and perform an initial coordinator update.
+        
+        Parameters:
+            coordinator (OasisDeviceCoordinator): Coordinator that manages device updates.
+            device (OasisDevice): The Oasis device this entity represents.
+            description (EntityDescription): Metadata describing this select entity.
+        """
         super().__init__(coordinator, device, description)
         self._handle_coordinator_update()
 
     async def async_select_option(self, option: str) -> None:
-        """Change the selected option."""
+        """
+        Select and apply the option identified by its display string.
+        
+        Parameters:
+            option (str): The display string of the option to select; the option's index in the current options list is used to apply the selection.
+        """
         await self.entity_description.select_fn(self.device, self.options.index(option))
 
     @callback
     def _handle_coordinator_update(self) -> None:
-        """Handle updated data from the coordinator."""
+        """
+        Update the entity's cached value and current option when coordinator data changes.
+        
+        If the derived current value differs from the stored value, update the stored value.
+        If the entity description provides an update_handler, call it with this entity; otherwise,
+        set the entity's current option to the string form of the device attribute named by the
+        description's key. If Home Assistant is available on the entity, delegate to the base
+        class's _handle_coordinator_update to propagate the state change.
+        """
         new_value = self.entity_description.current_value(self.device)
         if self._current_value == new_value:
             return
@@ -155,4 +209,4 @@ class OasisDeviceSelectEntity(OasisDeviceEntity, SelectEntity):
                 getattr(self.device, self.entity_description.key)
             )
         if self.hass:
-            return super()._handle_coordinator_update()
+            return super()._handle_coordinator_update()