docs: add docs to CB

Pretty much every class and method should have documentation now.

ref: N25B-295

src/control_backend/api/v1/endpoints/logs.py

@@ -15,6 +15,14 @@ router = APIRouter()
 # DO NOT LOG INSIDE THIS FUNCTION
 @router.get("/logs/stream")
 async def log_stream():
+    """
+    Server-Sent Events (SSE) endpoint for real-time log streaming.
+
+    Subscribes to the internal ZMQ logging topic and forwards log records to the client.
+    Allows the frontend to display live logs from the backend.
+
+    :return: A StreamingResponse yielding SSE data.
+    """
     context = Context.instance()
     socket = context.socket(zmq.SUB)
 

src/control_backend/api/v1/endpoints/message.py

@@ -11,6 +11,14 @@ router = APIRouter()
 
 @router.post("/message", status_code=202)
 async def receive_message(message: Message, request: Request):
+    """
+    Generic endpoint to receive text messages.
+
+    Publishes the message to the internal 'message' topic via ZMQ.
+
+    :param message: The message payload.
+    :param request: The FastAPI request object (used to access app state).
+    """
     logger.info("Received message: %s", message.message)
 
     topic = b"message"

src/control_backend/api/v1/endpoints/program.py

@@ -11,8 +11,14 @@ router = APIRouter()
 @router.post("/program", status_code=202)
 async def receive_message(program: Program, request: Request):
     """
-    Receives a BehaviorProgram, pydantic checks it.
-    Converts it into real Phase objects.
+    Endpoint to upload a new Behavior Program.
+
+    Validates the program structure (phases, norms, goals) and publishes it to the internal
+    'program' topic. The :class:`~control_backend.agents.bdi.bdi_program_manager.BDIProgramManager`
+    will pick this up and update the BDI agent.
+
+    :param program: The parsed Program object.
+    :param request: The FastAPI request object.
     """
     logger.debug("Received raw program: %s", program)
 

src/control_backend/api/v1/endpoints/robot.py

@@ -17,6 +17,16 @@ router = APIRouter()
 
 @router.post("/command", status_code=202)
 async def receive_command(command: SpeechCommand, request: Request):
+    """
+    Send a direct speech command to the robot.
+
+    Publishes the command to the internal 'command' topic. The
+    :class:`~control_backend.agents.actuation.robot_speech_agent.RobotSpeechAgent`
+    will forward this to the robot.
+
+    :param command: The speech command payload.
+    :param request: The FastAPI request object.
+    """
     # Validate and retrieve data.
     SpeechCommand.model_validate(command)
     topic = b"command"
@@ -29,12 +39,22 @@ async def receive_command(command: SpeechCommand, request: Request):
 
 @router.get("/ping_check")
 async def ping(request: Request):
+    """
+    Simple HTTP ping endpoint to check if the backend is reachable.
+    """
     pass
 
 
 @router.get("/ping_stream")
 async def ping_stream(request: Request):
-    """Stream live updates whenever the device state changes."""
+    """
+    SSE endpoint for monitoring the Robot Interface connection status.
+
+    Subscribes to the internal 'ping' topic (published by the RI Communication Agent)
+    and yields status updates to the client.
+
+    :return: A StreamingResponse of connection status events.
+    """
 
     async def event_stream():
         # Set up internal socket to receive ping updates

src/control_backend/api/v1/endpoints/sse.py

@@ -6,4 +6,7 @@ router = APIRouter()
 # TODO: implement
 @router.get("/sse")
 async def sse(request: Request):
+    """
+    Placeholder for future Server-Sent Events endpoint.
+    """
     pass