improving Python comments for Doxygen

.github/Doxyfile-cpp

@@ -530,7 +530,7 @@ EXTRACT_ALL            = YES
 # be included in the documentation.
 # The default value is: NO.
 
-EXTRACT_PRIVATE        = NO
+EXTRACT_PRIVATE        = YES
 
 # If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual
 # methods of a class will be included in the documentation.

.github/Doxyfile-python

@@ -530,7 +530,7 @@ EXTRACT_ALL            = YES
 # be included in the documentation.
 # The default value is: NO.
 
-EXTRACT_PRIVATE        = NO
+EXTRACT_PRIVATE        = YES
 
 # If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual
 # methods of a class will be included in the documentation.

yasmin/src/yasmin/state_machine.cpp

@@ -294,7 +294,7 @@ StateMachine::execute(std::shared_ptr<blackboard::Blackboard> blackboard) {
     if (std::find(state->get_outcomes().begin(), state->get_outcomes().end(),
                   outcome) == state->get_outcomes().end()) {
       throw std::logic_error("Outcome '" + outcome +
-                             "' is not register in state " +
+                             "' is not registered in state " +
                              this->current_state);
     }
 
@@ -331,9 +331,8 @@ StateMachine::execute(std::shared_ptr<blackboard::Blackboard> blackboard) {
 
       // Outcome is not in the sm
     } else {
-      throw std::logic_error(
-          "Outcome '" + outcome +
-          "' is not a state neither a state machine outcome");
+      throw std::logic_error("Outcome '" + outcome +
+                             "' is not a state nor a state machine outcome");
     }
   }
 

yasmin/yasmin/blackboard.py

@@ -1,65 +1,159 @@
 # Copyright (C) 2023  Miguel Ángel González Santamarta
-
+#
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
-
+#
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
-
+#
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-
 from typing import Any, Dict
 from threading import Lock
 
 import yasmin
 
 
 class Blackboard(object):
+    """
+    A thread-safe blackboard for storing key-value pairs.
+
+    The Blackboard class provides a mechanism to store data in a dictionary-like format,
+    allowing for concurrent access and modification through thread-safe operations.
+
+    Attributes:
+        _data (Dict[str, Any]): A dictionary holding the data stored in the blackboard.
+        __lock (Lock): A threading lock to ensure thread-safe access to the _data attribute.
+
+    Methods:
+        __getitem__(key): Retrieve a value associated with the given key.
+        __setitem__(key, value): Set a value for the given key.
+        __delitem__(key): Remove the value associated with the given key.
+        __contains__(key): Check if a key exists in the blackboard.
+        __len__(): Return the number of items in the blackboard.
+        __repr__(): Return a string representation of the blackboard's data.
+    """
+
+    __lock: Lock
+    _data: dict
 
     def __init__(self, init: Dict[str, Any] = None) -> None:
-        self.__lock = Lock()
-        self._data = {}
+        """
+        Initializes the Blackboard with an optional initial dictionary.
+
+        Args:
+            init (Dict[str, Any], optional): A dictionary to initialize the blackboard with.
+                If None, the blackboard starts empty.
+
+        Raises:
+            None
+        """
+        self.__lock = Lock()  # Lock for thread-safe operations
+        self._data = {}  # Dictionary to hold the data
+
         if init is not None:
-            self._data.update(init)
+            self._data.update(init)  # Initialize with provided data
+
+    def __getitem__(self, key: str) -> Any:
+        """
+        Retrieves a value from the blackboard associated with the specified key.
 
-    def __getitem__(self, key) -> Any:
+        Args:
+            key (str): The key whose value needs to be retrieved.
 
+        Returns:
+            Any: The value associated with the key.
+
+        Raises:
+            KeyError: If the key is not found in the blackboard.
+        """
         yasmin.YASMIN_LOG_DEBUG(f"Getting '{key}' from the blackboard")
 
         with self.__lock:
             return self._data[key]
 
-    def __setitem__(self, key, value) -> None:
+    def __setitem__(self, key: str, value: Any) -> None:
+        """
+        Sets a value in the blackboard for the specified key.
+
+        Args:
+            key (str): The key to associate with the value.
+            value (Any): The value to be stored in the blackboard.
+
+        Returns:
+            None
 
+        Raises:
+            None
+        """
         yasmin.YASMIN_LOG_DEBUG(f"Setting '{key}' in the blackboard")
 
         with self.__lock:
             self._data[key] = value
 
-    def __delitem__(self, key) -> None:
+    def __delitem__(self, key: str) -> None:
+        """
+        Removes the value associated with the specified key from the blackboard.
 
+        Args:
+            key (str): The key to be removed.
+
+        Returns:
+            None
+
+        Raises:
+            KeyError: If the key is not found in the blackboard.
+        """
         yasmin.YASMIN_LOG_DEBUG(f"Removing '{key}' from the blackboard")
 
         with self.__lock:
             del self._data[key]
 
-    def __contains__(self, key) -> bool:
+    def __contains__(self, key: str) -> bool:
+        """
+        Checks if a specified key exists in the blackboard.
+
+        Args:
+            key (str): The key to check for existence.
 
+        Returns:
+            bool: True if the key exists, False otherwise.
+
+        Raises:
+            None
+        """
         yasmin.YASMIN_LOG_DEBUG(f"Checking if '{key}' is in the blackboard")
 
         with self.__lock:
             return key in self._data
 
     def __len__(self) -> int:
+        """
+        Returns the number of items stored in the blackboard.
+
+        Returns:
+            int: The count of items in the blackboard.
+
+        Raises:
+            None
+        """
         with self.__lock:
             return len(self._data)
 
     def __repr__(self) -> str:
+        """
+        Returns a string representation of the blackboard's data.
+
+        Returns:
+            str: A string representation of the current state of the blackboard.
+
+        Raises:
+            None
+        """
         with self.__lock:
             return repr(self._data)

yasmin/yasmin/cb_state.py

@@ -1,29 +1,68 @@
 # Copyright (C) 2023  Miguel Ángel González Santamarta
-
+#
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
-
+#
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
-
+#
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-
 from typing import Set, Callable
+
 from yasmin.state import State
+from yasmin.blackboard import Blackboard
 
 
 class CbState(State):
+    """
+    CbState is a subclass of State that encapsulates a callback function
+    which can be executed in response to a specific state.
+
+    Attributes:
+        _cb (Callable): A callback function that defines the action to take
+                        when the state is executed.
+
+    Parameters:
+        outcomes (Set[str]): A set of possible outcomes for this state.
+        cb (Callable): A callable that will be invoked when the state is executed.
+    """
+
+    _cb: Callable  ##< A callable that will be invoked when the state is executed.
 
     def __init__(self, outcomes: Set[str], cb: Callable) -> None:
+        """
+        Initializes a new instance of CbState.
+
+        Args:
+            outcomes (Set[str]): A set of possible outcomes for this state.
+            cb (Callable): A callable that defines the action to take when
+                           the state is executed.
 
+        Raises:
+            TypeError: If 'outcomes' is not a set or 'cb' is not callable.
+        """
         super().__init__(outcomes)
         self._cb = cb
 
-    def execute(self, blackboard) -> str:
+    def execute(self, blackboard: Blackboard) -> str:
+        """
+        Executes the callback function with the provided blackboard context.
+
+        Args:
+            blackboard: The context in which the callback will be executed.
+                        This is typically an object that holds the necessary
+                        state or data for the callback.
+
+        Returns:
+            str: The result of the callback function execution.
+
+        Raises:
+            Exception: Propagates any exceptions raised by the callback function.
+        """
         return self._cb(blackboard)