docs: add docs to CB

Pretty much every class and method should have documentation now.

ref: N25B-295

src/control_backend/agents/communication/ri_communication_agent.py

@@ -12,6 +12,27 @@ from ..actuation.robot_speech_agent import RobotSpeechAgent
 
 
 class RICommunicationAgent(BaseAgent):
+    """
+    Robot Interface (RI) Communication Agent.
+
+    This agent manages the high-level connection negotiation and health checking (heartbeat)
+    between the Control Backend and the Robot Interface (or UI).
+
+    It acts as a service discovery mechanism:
+    1.  It initiates a handshake (negotiation) to discover where other services (like the robot
+        command listener) are listening.
+    2.  It spawns specific agents
+            (like :class:`~control_backend.agents.actuation.robot_speech_agent.RobotSpeechAgent`)
+        once the connection details are established.
+    3.  It maintains a "ping" loop to ensure the connection remains active.
+
+    :ivar _address: The ZMQ address to attempt the initial connection negotiation.
+    :ivar _bind: Whether to bind or connect the negotiation socket.
+    :ivar _req_socket: ZMQ REQ socket for negotiation and pings.
+    :ivar pub_socket: ZMQ PUB socket for internal notifications (e.g., ping status).
+    :ivar connected: Boolean flag indicating active connection status.
+    """
+
     def __init__(
         self,
         name: str,
@@ -27,8 +48,10 @@ class RICommunicationAgent(BaseAgent):
 
     async def setup(self):
         """
-        Try to set up the communication agent, we have `behaviour_settings.comm_setup_max_retries`
-        retries in case we don't have a response yet.
+        Initialize the agent and attempt connection.
+
+        Tries to negotiate connection up to ``behaviour_settings.comm_setup_max_retries`` times.
+        If successful, starts the :meth:`_listen_loop`.
         """
         self.logger.info("Setting up %s", self.name)
 
@@ -45,7 +68,7 @@ class RICommunicationAgent(BaseAgent):
 
     async def _setup_sockets(self, force=False):
         """
-        Sets up request socket for communication agent.
+        Initialize ZMQ sockets (REQ for negotiation, PUB for internal updates).
         """
         # Bind request socket
         if self._req_socket is None or force:
@@ -62,6 +85,15 @@ class RICommunicationAgent(BaseAgent):
     async def _negotiate_connection(
         self, max_retries: int = settings.behaviour_settings.comm_setup_max_retries
     ):
+        """
+        Perform the handshake protocol with the Robot Interface.
+
+        Sends a ``negotiate/ports`` request and expects a configuration response containing
+        port assignments for various services (e.g., actuation).
+
+        :param max_retries: Number of attempts before giving up.
+        :return: True if negotiation succeeded, False otherwise.
+        """
         retries = 0
         while retries < max_retries:
             if self._req_socket is None:
@@ -122,6 +154,12 @@ class RICommunicationAgent(BaseAgent):
         return False
 
     async def _handle_negotiation_response(self, received_message):
+        """
+        Parse the negotiation response and initialize services.
+
+        Based on the response, it might re-connect the main socket or spawn new agents
+        (e.g., for robot actuation).
+        """
         for port_data in received_message["data"]:
             id = port_data["id"]
             port = port_data["port"]
@@ -159,7 +197,10 @@ class RICommunicationAgent(BaseAgent):
 
     async def _listen_loop(self):
         """
-        Run the listening (ping) loop indefinitely.
+        Maintain the connection via a heartbeat (ping) loop.
+
+        Sends a ``ping`` request periodically and waits for a reply.
+        If pings fail repeatedly, it triggers a disconnection handler to restart negotiation.
         """
         while self._running:
             if not self.connected:
@@ -217,6 +258,11 @@ class RICommunicationAgent(BaseAgent):
                 raise
 
     async def _handle_disconnection(self):
+        """
+        Handle connection loss.
+
+        Notifies the UI of disconnection (via internal PUB) and attempts to restart negotiation.
+        """
         self.connected = False
 
         # Tell UI we're disconnected.