Improve main function docstrings

Author: bouwew

plugwise/__init__.py

@@ -305,15 +305,15 @@ async def _smile_detect_legacy(
         return return_model
 
     async def full_xml_update(self) -> None:
-        """Helper-function used for testing."""
+        """Perform a first fetch of the Plugwise server XML data."""
         await self._smile_api.full_xml_update()
 
     def get_all_gateway_entities(self) -> None:
-        """Helper-function used for testing."""
+        """Collect the Plugwise gateway entities and their data and states from the received raw XML-data."""
         self._smile_api.get_all_gateway_entities()
 
     async def async_update(self) -> PlugwiseData:
-        """Update the various entities and their states."""
+        """Update the Plughwise gateway entities and their data and states."""
         data = PlugwiseData(devices={}, gateway={})
         try:
             data = await self._smile_api.async_update()

plugwise/legacy/smile.py

@@ -83,7 +83,7 @@ def __init__(
         self._previous_day_number: str = "0"
 
     async def full_xml_update(self) -> None:
-        """Perform a first fetch of all XML data, needed for initialization."""
+        """Perform a first fetch of the Plugwise server XML data."""
         self._domain_objects = await self.request(DOMAIN_OBJECTS)
         self._locations = await self.request(LOCATIONS)
         self._modules = await self.request(MODULES)
@@ -92,24 +92,23 @@ async def full_xml_update(self) -> None:
             self._appliances = await self.request(APPLIANCES)
 
     def get_all_gateway_entities(self) -> None:
-        """Collect the gateway entities from the received raw XML-data.
+        """Collect the Plugwise gateway entities and their data and states from the received raw XML-data.
 
-        Run this functions once to gather the initial device configuration,
-        then regularly run async_update() to refresh the device data.
+        First, collect all the connected entities and their initial data.
+        Collect and add switching- and/or pump-group entities.
+        Finally, collect the data and states for each entity.
         """
-        # Gather all the devices and their initial data
         self._all_appliances()
-
-        # Collect and add switching- and/or pump-group devices
         if group_data := self._get_group_switches():
             self.gw_entities.update(group_data)
 
-        # Collect the remaining data for all entities
         self._all_entity_data()
 
     async def async_update(self) -> PlugwiseData:
-        """Perform an incremental update for updating the various device states."""
-        # Perform a full update at day-change
+        """Perform an full update update at day-change: re-collect all gateway entities and their data and states.
+
+        Otherwise perform an incremental update: only collect the entities updated data and states.
+        """
         day_number = dt.datetime.now().strftime("%w")
         if (
             day_number  # pylint: disable=consider-using-assignment-expr
@@ -129,7 +128,6 @@ async def async_update(self) -> PlugwiseData:
                 raise DataMissingError(
                     "No (full) Plugwise legacy data received"
                 ) from err
-        # Otherwise perform an incremental update
         else:
             try:
                 self._domain_objects = await self.request(DOMAIN_OBJECTS)

plugwise/smile.py

@@ -97,42 +97,43 @@ def __init__(
         SmileData.__init__(self)
 
     async def full_xml_update(self) -> None:
-        """Perform a first fetch of all XML data, needed for initialization."""
+        """Perform a first fetch of the Plugwise server XML data."""
         self._domain_objects = await self.request(DOMAIN_OBJECTS)
         self._get_plugwise_notifications()
 
     def get_all_gateway_entities(self) -> None:
-        """Collect the gateway entities from the received raw XML-data.
+        """Collect the Plugwise gateway entities and their data and states from the received raw XML-data.
 
-        Run this functions once to gather the initial configuration,
-        then regularly run async_update() to refresh the entity data.
+        First, collect all the connected entities and their initial data.
+        If a thermostat-gateway, collect a list of thermostats with offset-capability.
+        Collect and add switching- and/or pump-group entities.
+        Finally, collect the data and states for each entity.
         """
-        # Gather all the entities and their initial data
         self._all_appliances()
         if self._is_thermostat:
-            if self.smile(ADAM):
-                self._scan_thermostats()
-            # Collect a list of thermostats with offset-capability
             self.therms_with_offset_func = (
                 self._get_appliances_with_offset_functionality()
             )
+            if self.smile(ADAM):
+                self._scan_thermostats()
 
-        # Collect and add switching- and/or pump-group devices
         if group_data := self._get_group_switches():
             self.gw_entities.update(group_data)
 
-        # Collect the remaining data for all entities
         self._all_entity_data()
 
     async def async_update(self) -> PlugwiseData:
-        """Perform an incremental update for updating the various device states."""
+        """Perform an full update: re-collect all gateway entities and their data and states.
+
+        Any change in the connected entities will be detected immediately.
+        """
         self.gw_data: GatewayData = {}
         self.gw_entities: dict[str, GwEntityData] = {}
         self._zones: dict[str, GwEntityData] = {}
         try:
             await self.full_xml_update()
             self.get_all_gateway_entities()
-            # Set self._cooling_enabled - required for set_temperature,
+            # Set self._cooling_enabled - required for set_temperature(),
             # also, check for a failed data-retrieval
             if "heater_id" in self.gw_data:
                 heat_cooler = self.gw_entities[self.gw_data["heater_id"]]