From 04780bd0dd060dc045a07f6f879f4540ed1d028e Mon Sep 17 00:00:00 2001
From: Sven Sager <akira@narux.de>
Date: Mon, 21 Apr 2025 14:42:14 +0200
Subject: [PATCH] doc(revpiconfig): Add docstrings to `RevPiConfig` class and
 methods

Enhance documentation for the `RevPiConfig` class, its methods, and
properties to improve code readability and ease of use. The added
docstrings provide clear explanations of the class's purpose,
attributes, and functionality for developers and users. This update
supports better maintainability and understanding of the codebase.
---
 .../system_config/revpi_config.py             | 76 +++++++++++++++++++
 1 file changed, 76 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 0b7fabe..c63eec1 100644
--- a/src/revpi_middleware/dbus_middleware1/system_config/revpi_config.py
+++ b/src/revpi_middleware/dbus_middleware1/system_config/revpi_config.py
@@ -42,6 +42,20 @@ class ConfigActions(Enum):
 
 
 class RevPiConfig:
+    """
+    Represents the configuration and hardware details of a Revolution Pi system.
+
+    This class provides methods and properties to initialize and fetch
+    information related to the Revolution Pi device, such as model, serial
+    number, compute module type, WLAN capability, and the presence of a
+    connection bridge. The class works by parsing system-level files (e.g.,
+    `/proc/cpuinfo`) and using this data to identify hardware characteristics
+    and features.
+
+    Attributes:
+        serial (str): The serial number of the Revolution Pi device.
+        model (str): The model name of the Revolution Pi device.
+    """
 
     def __init__(self):
         self._cm_type = ComputeModuleTypes.UNKNOWN
@@ -55,6 +69,29 @@ class RevPiConfig:
         self._init_device_info()
 
     def _init_device_info(self):
+        """
+        Initialize and retrieve detailed hardware information, including CPU details,
+        device type, WLAN interface, and connectivity features.
+
+        This method gathers information from system files and other sources to
+        initialize device-specific attributes such as model, serial number,
+        compute module type, and optional features like integrated WLAN
+        or ConBridge support. It performs checks specific to the detected
+        module type to accurately populate necessary device details.
+
+        Attributes
+        ----------
+        model : str
+            The model of the CPU based on information from /proc/cpuinfo.
+        serial : str
+            The serial number extracted from /proc/cpuinfo.
+        _cm_type : ComputeModuleTypes, optional
+            The type of the compute module derived from the hardware revision value.
+        _wlan_class_path : str, optional
+            Filesystem path to the detected WLAN interface, if any.
+        _revpi_with_con_bridge : bool
+            Indicates whether the device supports the ConBridge feature.
+        """
         dc_cpuinfo = {}
 
         # Extract CPU information
@@ -103,18 +140,57 @@ class RevPiConfig:
 
     @property
     def class_path_wlan(self) -> str:
+        """
+        Provides access to the WLAN class path.
+
+        This property retrieves the stored WLAN class path, allowing the user to access it when
+        needed.
+
+        Returns:
+            str: The WLAN class path.
+        """
         return self._wlan_class_path
 
     @property
     def cm_type(self) -> ComputeModuleTypes:
+        """
+        Gets the type of the compute module.
+
+        The property provides access to the type of the compute
+        module used. The type is represented as an instance of
+        the `ComputeModuleTypes` class.
+
+        Returns
+        -------
+        ComputeModuleTypes
+            The type of the compute module.
+        """
         return self._cm_type
 
     @property
     def with_con_bridge(self) -> bool:
+        """
+        Indicates if the device is configured with a connection bridge.
+
+        This property checks the internal status and determines whether the device setup
+        includes a connection bridge functionality. It is read-only.
+
+        Returns:
+            bool: True if the connection bridge is configured, False otherwise.
+        """
         return self._revpi_with_con_bridge
 
     @property
     def with_wlan(self) -> bool:
+        """
+        Checks if WLAN is available.
+
+        This property evaluates whether WLAN is enabled or available by checking
+        the presence or value of the internal attribute `_wlan_class_path`.
+
+        Returns:
+            bool: True if WLAN is available, False otherwise.
+        """
         return bool(self._wlan_class_path)