[occ] Improve documentation

Author: teo

occ/occlib/OccInstance.h

@@ -57,8 +57,13 @@ class OCC_EXPORT OccInstance
      *
      * @see OccGlobals.h
      *
-     * @note This constructor spawns a server thread for gRPC. Incoming message handlers are triggered
-     *  from there and eventually result in calls to the transition functions in RuntimeControlledObject.
+     * @note This constructor spawns two additional threads: a server thread for gRPC, and an event loop
+     *  thread for managing the states of the RuntimeControlledObject (indirectly, via the OccServer
+     *  constructor).
+     *  Incoming message handlers are triggered from the server thread and eventually result in
+     *  calls to the transition functions in RuntimeControlledObject.
+     *  Additionally, the event loop thread runs in every state to allow the implementer to report
+     *  an error or finished condition.
      *  The OccInstance destructor takes care of safely tearing down this server.
      */
     explicit OccInstance(RuntimeControlledObject *rco, int controlPort = 0);

occ/occlib/OccServer.h

@@ -53,8 +53,21 @@ const std::unordered_map<std::string, std::string> EXPECTED_FINAL_STATE = {
 class OccServer final : public pb::Occ::Service
 {
 public:
+    /**
+     * Instantiate the gRPC-based control message server.
+     *
+     * @param rco a pointer to the RuntimeControlledObject-derived state machine.
+     *
+     * @note This constructor spawns an additional thread which acts as event loop to check the
+     *  state of the RuntimeControlledObject.
+     *
+     * @see OccInstance
+     */
     explicit OccServer(RuntimeControlledObject* rco);
 
+    /**
+     * Tears down the OccServer.
+     */
     virtual ~OccServer();
 
     grpc::Status StateStream(grpc::ServerContext* context,