chore(network): drop per-poll debug logs and add missing docstrings (#308)

# Description
- [x] Documentation

Stacked on #1, review after it merges.

Removes per-poll debug logging that was spamming the log directory,
compresses comments to one-liners, adds missing docstrings across the
network layer (buys docstr-coverage margin for the rest of the stack,
baseline 80.1% against an 80% gate).

- Drop noisy per-poll debug logs
- Compress multi-line comments to one-liners
- Add docstrings for pre-existing gaps

# Tests
All 5 gates pass standing alone. No behaviour change (docs/logging
only).

Author: gmmcosta15

BlocksScreen/lib/network/manager.py

@@ -1,3 +1,5 @@
+"""Qt-facing NetworkManager facade: owns the worker thread and its signals."""
+
 # pylint: disable=protected-access
 
 import asyncio
@@ -17,7 +19,7 @@
 
 logger = logging.getLogger(__name__)
 
-_KEEPALIVE_POLL_MS: int = 300_000  # 5 minutes — safety net for missed signals
+_KEEPALIVE_POLL_MS: int = 300_000  # 5 minutes: safety net for missed signals
 
 
 class NetworkManager(QObject):
@@ -27,9 +29,9 @@ class NetworkManager(QObject):
     a ``NetworkManagerWorker`` that runs all D-Bus coroutines on its
     dedicated asyncio thread.
 
-    Coroutines are submitted to ``worker._asyncio_loop`` — the same loop
-    on which the D-Bus file-descriptor was registered — so signal delivery
-    and async I/O always occur on the correct selector.
+    Coroutines are submitted to ``worker._asyncio_loop`` (the same loop the
+    D-Bus file-descriptor was registered on), so signal delivery and async
+    I/O always occur on the correct selector.
 
     """
 
@@ -72,7 +74,7 @@ def __init__(self, parent: QObject | None = None) -> None:
         self._worker.reconnect_complete.connect(self.reconnect_complete)
         self._worker.initialized.connect(self._on_worker_initialized)
 
-        # Keepalive timer — safety net for any missed D-Bus signals.
+        # Keepalive timer: safety net for any missed D-Bus signals.
         self._keepalive_timer = QTimer(self)
         self._keepalive_timer.setInterval(_KEEPALIVE_POLL_MS)
         self._keepalive_timer.timeout.connect(self._on_keepalive_tick)
@@ -96,7 +98,7 @@ def _schedule(self, coro: "asyncio.Coroutine") -> None:
             future.add_done_callback(self._pending_futures.discard)
         else:
             logger.debug(
-                "Dropping early coroutine — loop not yet running: %s",
+                "Dropping early coroutine, loop not yet running: %s",
                 coro.__qualname__,
             )
             coro.close()
@@ -114,7 +116,7 @@ def _on_worker_initialized(self) -> None:
             return
         self._worker_ready = True
         logger.info(
-            "Worker initialised — starting keepalive (every %d ms)",
+            "Worker initialised: starting keepalive (every %d ms)",
             _KEEPALIVE_POLL_MS,
         )
         self._keepalive_timer.start()
@@ -185,7 +187,7 @@ def _on_hotspot_info_ready(self, ssid: str, password: str, security: str) -> Non
 
     @pyqtSlot()
     def _on_keepalive_tick(self) -> None:
-        """Safety-net refresh — runs every 5 min to catch any missed signals."""
+        """Safety-net refresh: runs every 5 min to catch any missed signals."""
         if self._shutting_down:
             return
         self._schedule(self._worker._async_get_current_state())
@@ -273,7 +275,7 @@ def update_hotspot_config(
         new_password: str,
         security: str = "wpa-psk",
     ) -> None:
-        """Change hotspot name/password/security — cleans up old profiles."""
+        """Change hotspot name/password/security: cleans up old profiles."""
         self._schedule(
             self._worker._async_update_hotspot_config(
                 old_ssid, new_ssid, new_password, security
@@ -346,17 +348,17 @@ def saved_networks(self) -> list[SavedNetwork]:
 
     @property
     def hotspot_ssid(self) -> str:
-        """Hotspot SSID — read from main-thread cache (thread-safe)."""
+        """Hotspot SSID: read from main-thread cache (thread-safe)."""
         return self._cached_hotspot_ssid
 
     @property
     def hotspot_password(self) -> str:
-        """Hotspot password — read from main-thread cache (thread-safe)."""
+        """Hotspot password: read from main-thread cache (thread-safe)."""
         return self._cached_hotspot_password
 
     @property
     def hotspot_security(self) -> str:
-        """Hotspot security type — always 'wpa-psk' (WPA2-PSK, thread-safe)."""
+        """Hotspot security type: always 'wpa-psk' (WPA2-PSK, thread-safe)."""
         return self._cached_hotspot_security
 
     def get_network_info(self, ssid: str) -> NetworkInfo | None:

BlocksScreen/lib/network/models.py

@@ -82,8 +82,8 @@ class NetworkStatus(IntEnum):
     ``NetworkInfo.is_open`` (derived from ``security_type``) instead.
     """
 
-    DISCOVERED = 0  # Seen in scan, not saved — protected security
-    OPEN = 1  # Seen in scan, not saved — open (no passphrase)
+    DISCOVERED = 0  # Seen in scan, not saved: protected security
+    OPEN = 1  # Seen in scan, not saved: open (no passphrase)
     SAVED = 2  # Profile saved on this device
     ACTIVE = 3  # Currently connected
     HIDDEN = 4  # Hidden-network placeholder
@@ -287,7 +287,7 @@ class HotspotSecurity(str, Enum):
     """
 
     WPA1 = "wpa1"
-    WPA2_PSK = "wpa-psk"  # WPA2-PSK (CCMP) — default
+    WPA2_PSK = "wpa-psk"  # WPA2-PSK (CCMP): default
 
     @classmethod
     def is_valid(cls, value: str) -> bool:

BlocksScreen/lib/network/worker.py

@@ -1,3 +1,5 @@
+"""Async D-Bus NetworkManager worker: signal watching, link control, state snapshots."""
+
 import asyncio
 import fcntl
 import ipaddress
@@ -476,21 +478,19 @@ async def _listen_ap_added(self) -> None:
         if not self._signal_wifi:
             return
         logger.debug("AP Added listener started on %s", self._primary_wifi_path)
-        async for ap_path in self._signal_wifi.access_point_added:
+        async for _ in self._signal_wifi.access_point_added:
             if not self._running:
                 return
-            logger.debug("AP added: %s", ap_path)
             self._schedule_debounced_scan()
 
     async def _listen_ap_removed(self) -> None:
         """React to access points disappearing from scan results."""
         if not self._signal_wifi:
             return
         logger.debug("AP Removed listener started on %s", self._primary_wifi_path)
-        async for ap_path in self._signal_wifi.access_point_removed:
+        async for _ in self._signal_wifi.access_point_removed:
             if not self._running:
                 return
-            logger.debug("AP removed: %s", ap_path)
             self._schedule_debounced_scan()
 
     async def _listen_wired_state_changed(self) -> None:
@@ -836,7 +836,6 @@ async def _build_current_state(self) -> NetworkState:
                         current_ip = _fallback
                         if _iface != "wlan0":
                             eth_connected = True
-                        logger.debug("OS fallback IP for '%s': %s", _iface, _fallback)
                         break
 
             signal = 0
@@ -852,10 +851,6 @@ async def _build_current_state(self) -> NetworkState:
             if not hotspot_enabled and self._is_hotspot_active and not current_ssid:
                 hotspot_enabled = True
                 current_ssid = self._hotspot_config.ssid
-                logger.debug(
-                    "Hotspot SSID not found via D-Bus, using config: '%s'",
-                    current_ssid,
-                )
 
             if hotspot_enabled:
                 sec_type = self._hotspot_config.security

BlocksScreen/lib/panels/networkWindow.py

@@ -1,3 +1,5 @@
+"""Network settings UI: Wi-Fi, ethernet and hotspot panels backed by the NM manager."""
+
 import fcntl
 import ipaddress as _ipaddress
 import logging