doc(revpiconfig): Add detailed docstrings to ConfigTxt methods

Enhance the `ConfigTxt` class with comprehensive docstrings for all
methods, providing clear explanations of their functionality,
parameters, and return values. This improves code readability and
facilitates easier maintenance and understanding for future developers.

src/revpi_middleware/dbus_middleware1/system_config/revpi_config.py

@@ -119,6 +119,20 @@ class RevPiConfig:
 
 
 class ConfigTxt:
+    """
+    Configuration file handler for managing 'config.txt'.
+
+    This class provides an interface to read, modify, save, and reload
+    Raspbian's configuration file `config.txt`. It includes functionalities
+    to manipulate specific parameters within the configuration and supports
+    managing dtoverlay and dtparam entries. The primary aim of this class
+    is to abstract file operations and make modifications user-friendly.
+
+    Attributes:
+        _config_txt_path (str): The path to the configuration file `config.txt`.
+        _config_txt_lines (list[str]): Contains all lines of the configuration
+            file as a list of strings, where each string represents a line.
+    """
     re_name_value = re.compile(r"^\s*(?!#)(?P<name>[^=\s].+?)\s*=\s*(?P<value>\S+)\s*$")
 
     def __init__(self):
@@ -134,6 +148,24 @@ class ConfigTxt:
         self._config_txt_lines = []
 
     def _clear_name_values(self, name: str, values: str or list) -> int:
+        """
+        Removes all occurrences of specified name-value pairs from the configuration.
+
+        This method searches for all name-value pairs in the configuration and
+        removes those that match the given name and value(s). It returns the
+        number of occurrences removed.
+
+        Arguments:
+            name: str
+                The name of the configuration variable to search for.
+            values: str or list
+                The value or list of values to match the configuration variable
+                against.
+
+        Returns:
+            int: The number of name-value pairs removed from the configuration.
+
+        """
         counter = 0
         if type(values) is str:
             values = [values]
@@ -146,6 +178,21 @@ class ConfigTxt:
         return counter
 
     def _get_all_name_values(self) -> List[ConfigVariable]:
+        """
+        Retrieves all name-value pairs from the configuration text lines.
+
+        This method parses the configuration text lines to extract all name-value
+        pairs. If the configuration text lines are not loaded, it reloads the
+        configuration before processing. Each extracted name-value pair is added to a
+        list as a ConfigVariable object, which also holds the index of the match in
+        the text lines. The method returns the compiled list of these ConfigVariable
+        objects.
+
+        Returns:
+            List[ConfigVariable]: A list of ConfigVariable objects representing the
+            name-value pairs found in the configuration text lines, along with their
+            corresponding indexes.
+        """
         if not self._config_txt_lines:
             self.reload_config()
 
@@ -159,10 +206,28 @@ class ConfigTxt:
         return lst_return
 
     def reload_config(self):
+        """
+        Reloads the configuration file and updates the list of configuration lines.
+
+        This method reads the content of the configuration file specified by the
+        attribute `_config_txt_path` and updates `_config_txt_lines` with the file
+        contents as a list of strings, where each string represents a line.
+
+        Returns:
+            None
+        """
         with open(self._config_txt_path, "r") as f:
             self._config_txt_lines = f.readlines()
 
     def save_config(self):
+        """
+        Saves the current configuration to a file. The method ensures atomicity by first writing
+        to a temporary file and then moving it to the desired path. After the configuration is
+        saved, the internal list of configuration lines is cleared.
+
+        Raises:
+            OSError: If there is an issue writing to or moving the file.
+        """
         if not self._config_txt_lines:
             return
 
@@ -174,6 +239,20 @@ class ConfigTxt:
         self._config_txt_lines.clear()
 
     def add_name_value(self, name: str, value: str):
+        """
+        Adds a name-value pair to the configuration if it does not already exist.
+
+        This method checks if the given name-value pair is already present in
+        the configuration. If it is not present, the pair is appended to the
+        configuration text lines.
+
+        Parameters:
+            name (str): The name to be added to the configuration.
+            value (str): The value corresponding to the name to be added.
+
+        Returns:
+            None
+        """
         # Check weather name and value already exists
         for config_var in self._get_all_name_values():
             if config_var.name == name and config_var.value == value:
@@ -182,12 +261,55 @@ class ConfigTxt:
         self._config_txt_lines.append(f"{name}={value}\n")
 
     def clear_dtoverlays(self, dtoverlays: str or list) -> int:
+        """
+        Clears the specified device tree overlays. This method removes one or more
+        device tree overlays by clearing their corresponding name-value pairs.
+
+        Args:
+            dtoverlays (str or list): A device tree overlay name as a string, or a
+            list of such overlay names to be cleared.
+
+        Returns:
+            int: The number of device tree overlay name-value pairs successfully
+            cleared.
+        """
         return self._clear_name_values("dtoverlay", dtoverlays)
 
     def clear_dtparams(self, dtparams: str or list) -> int:
+        """
+        Clears the specified device tree parameters.
+
+        This method removes the given device tree parameters by utilizing
+        the underlying `_clear_name_values` function with a predefined
+        parameter type.
+
+        Parameters:
+        dtparams: str or list
+            A string or list of strings specifying the device tree
+            parameters to remove.
+
+        Returns:
+        int
+            The number of parameters cleared.
+        """
         return self._clear_name_values("dtparam", dtparams)
 
     def get_values(self, var_name: str) -> list:
+        """
+        Get all values associated with a given variable name.
+
+        This method retrieves a list of values corresponding to the specified
+        variable name by iterating through a collection of configuration
+        variables. Each configuration variable is checked for a matching name,
+        and its value is appended to the resulting list if a match is found.
+
+        Parameters:
+        var_name (str): The name of the variable for which values are to
+                        be retrieved.
+
+        Returns:
+        list: A list of values associated with the specified variable name.
+        """
         var_values = []
 
         for config_var in self._get_all_name_values():
@@ -198,6 +320,16 @@ class ConfigTxt:
 
     @property
     def config_txt_path(self) -> str:
+        """
+        Get the file path for the configuration text file.
+
+        This property provides access to the private attribute `_config_txt_path` which
+        stores the file path to the configuration text file.
+
+        Returns:
+        str
+            The file path to the configuration text file.
+        """
         return self._config_txt_path