From 8db1f59cfe897f02897874480caf55cf8238ca9c Mon Sep 17 00:00:00 2001
From: Sven Sager <akira@narux.de>
Date: Mon, 21 Apr 2025 14:44:50 +0200
Subject: [PATCH] doc(revpiconfig): Docstrings for `get_rfkill_index` and
 `simple_systemd`

The new docstrings provide detailed explanations of the purpose,
parameters, and return values for both functions, improving code
readability and maintainability. This ensures better understanding for
future contributors and reduces ambiguity.
---
 .../system_config/revpi_config.py             | 40 +++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/src/revpi_middleware/dbus_middleware1/system_config/revpi_config.py b/src/revpi_middleware/dbus_middleware1/system_config/revpi_config.py
index e58d9b2..00c809d 100644
--- a/src/revpi_middleware/dbus_middleware1/system_config/revpi_config.py
+++ b/src/revpi_middleware/dbus_middleware1/system_config/revpi_config.py
@@ -607,6 +607,23 @@ def configure_wlan(action: ConfigActions):
 
 
 def get_rfkill_index(device_class_path: str) -> Optional[int]:
+    """
+    Get the rfkill index for a device under a specific device class path.
+
+    This function searches for and extracts the rfkill index associated with
+    devices located under the given device class path. It uses a regular
+    expression to identify and parse the rfkill index from the paths
+    of matching rfkill device files.
+
+    Parameters:
+        device_class_path: str
+            The path to the device class directory where rfkill entries
+            are located.
+
+    Returns:
+        Optional[int]:
+            The index of the rfkill device if found, otherwise None.
+    """
     re_rfkill_index = re.compile(r"^/.+/rfkill(?P<index>\d+)$")
     for rfkill_path in glob(join(device_class_path, "rfkill*")):
         match_index = re_rfkill_index.match(rfkill_path)
@@ -617,6 +634,29 @@ def get_rfkill_index(device_class_path: str) -> Optional[int]:
 
 
 def simple_systemd(action: ConfigActions, unit: str):
+    """
+    Performs specified actions on systemd units.
+
+    This function allows interaction with systemd units for various operations
+    such as enabling, disabling, checking the status, and verifying availability.
+    It communicates with the systemd manager via the SystemBus and handles units
+    based on the action specified.
+
+    Parameters:
+        action (ConfigActions): Specifies the action to be performed on the
+                                systemd unit. Supported actions include ENABLE,
+                                DISABLE, STATUS, and AVAILABLE.
+        unit (str): The name of the systemd unit on which the action is to be
+                    performed.
+
+    Returns:
+        bool: For STATUS and AVAILABLE actions, returns True if the corresponding
+              criteria are met (e.g., enabled and active for STATUS, or not found
+              for AVAILABLE). Otherwise, returns False.
+
+    Raises:
+        ValueError: If the specified action is not supported.
+    """
     bus = SystemBus()
     systemd = bus.get(
         "org.freedesktop.systemd1",