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

@@ -33,13 +33,28 @@ class OasisDeviceConfigFlow(ConfigFlow, domain=DOMAIN):
     async def async_step_reauth(
         self, entry_data: Mapping[str, Any]
     ) -> ConfigFlowResult:
-        """Perform reauth upon an API authentication error."""
+        """
+        Begin the reauthentication flow for an existing config entry.
+        
+        Parameters:
+            entry_data (Mapping[str, Any]): Data from the existing config entry that triggered the reauthentication flow.
+        
+        Returns:
+            ConfigFlowResult: Result that presents the reauthentication confirmation dialog to the user.
+        """
         return await self.async_step_reauth_confirm()
 
     async def async_step_reauth_confirm(
         self, user_input: dict[str, Any] | None = None
     ) -> ConfigFlowResult:
-        """Dialog that informs the user that reauth is required."""
+        """
+        Present a reauthentication confirmation form to the user.
+        
+        If `user_input` is provided it will be used as the form values; otherwise the existing entry's data are used as suggested values.
+        
+        Returns:
+            ConfigFlowResult: Result of the config flow step that renders the reauthentication form or advances the flow.
+        """
         entry = self.hass.config_entries.async_get_entry(self.context["entry_id"])
         assert entry
 
@@ -51,7 +66,15 @@ class OasisDeviceConfigFlow(ConfigFlow, domain=DOMAIN):
     async def async_step_user(
         self, user_input: dict[str, Any] | None = None
     ) -> ConfigFlowResult:
-        """Handle the initial step."""
+        """
+        Handle the initial user configuration step for the Oasis integration.
+        
+        Parameters:
+            user_input (dict[str, Any] | None): Optional prefilled values (e.g., `email`, `password`) submitted by the user.
+        
+        Returns:
+            ConfigFlowResult: Result of the "user" step — a form prompting for credentials, an abort, or a created/updated config entry.
+        """
         return await self._async_step(
             "user", STEP_USER_DATA_SCHEMA, user_input, user_input
         )
@@ -75,7 +98,20 @@ class OasisDeviceConfigFlow(ConfigFlow, domain=DOMAIN):
         user_input: dict[str, Any] | None = None,
         suggested_values: dict[str, Any] | None = None,
     ) -> ConfigFlowResult:
-        """Handle step setup."""
+        """
+        Handle a single config flow step: validate input, create or update entries, or render the form.
+        
+        If valid credentials are provided, this will create a new config entry (title set to the provided email) or update an existing entry and trigger a reload. The step will abort if the validated account conflicts with an existing entry's unique ID. If no input is provided or validation fails, the flow returns a form populated with the given schema, any suggested values, and validation errors.
+        
+        Parameters:
+            step_id: Identifier of the flow step to render or process.
+            schema: Voluptuous schema used to build the form.
+            user_input: Submitted values from the form; when present, used for validation and entry creation/update.
+            suggested_values: Values to pre-fill into the form schema when rendering.
+        
+        Returns:
+            A ConfigFlowResult representing either a created entry, an update-and-reload abort, an abort due to a unique-id conflict, or a form to display with errors and suggested values.
+        """
         errors = {}
 
         if user_input is not None:
@@ -105,7 +141,21 @@ class OasisDeviceConfigFlow(ConfigFlow, domain=DOMAIN):
         )
 
     async def validate_client(self, user_input: dict[str, Any]) -> dict[str, str]:
-        """Validate client setup."""
+        """
+        Validate provided credentials by attempting to authenticate with the Oasis API and retrieve the user's identity.
+        
+        Parameters:
+            user_input (dict[str, Any]): Mutable credential mapping containing at least `email` and `password`.
+                On success, this mapping will be updated with `CONF_ACCESS_TOKEN` (the received access token)
+                and the `password` key will be removed.
+        
+        Returns:
+            dict[str, str]: A mapping of form field names to error keys. Common keys:
+                - `"base": "invalid_auth"` when credentials are incorrect or connection refused.
+                - `"base": "timeout_connect"` when the authentication request times out.
+                - `"base": "unknown"` for unexpected errors.
+                - `"base": "<http error text>"` when the server returns an HTTP error.
+        """
         errors = {}
         try:
             async with asyncio.timeout(10):
@@ -134,4 +184,4 @@ class OasisDeviceConfigFlow(ConfigFlow, domain=DOMAIN):
             errors["base"] = "unknown"
         finally:
             await client.async_close()
-        return errors
+        return errors