Revize 313ff1dc

Re #8906 - Server doc comments; cleanup

deltarobot/curvedataserver.h

@@ -8 +8 @@
 #include <mutex>
 #include <thread>
 
+
+/**
+ * Manages communication with clients who can connect to the server in order to receive real-time data about the current
+ * exercise. The served data may be used e.g. for external visualization. A reference implementation of such a client is
+ * the deltarobot-vr Unity application.
+ */
 class CurveDataServer : QObject
 {
     Q_OBJECT
 
 public:
+
+    /**
+     * Holds information about a client, its Qt socket, data buffer etc.
+     */
     struct Client {
         static const size_t BUF_SIZE = 4096;
         static const size_t MESSAGE_ID_SIZE = 2;
 
-        QTcpSocket* socket;
-        std::map<uint64_t, uint64_t> ping;  ///< key: ping ID;  value: ping timestamp (msec);
-        uint64_t latency;               ///< client's latency
-        uint64_t lastPong;              ///< timestamp of last pong
+        QTcpSocket* socket;                 ///< Communication socket
+        std::map<uint64_t, uint64_t> ping;  ///< Key: ping ID;  Value: ping timestamp (msec);
+        uint64_t latency;                   ///< Current latency
+        uint64_t lastPong;                  ///< Timestamp of the last pong
 
-        char buf[BUF_SIZE];
-        size_t bufUsed;
+        char buf[BUF_SIZE];                 ///< Message buffer
+        size_t bufUsed = 0;                 ///< Number of bytes used up in the message buffer
 
-        bool magic = false;
-        bool version = false;
-        bool initialized = false;
+        bool magic = false;                 ///< Whether the client has sent the protocol magic
+        bool version = false;               ///< Whether the client has sent the protocol version
+        bool initialized = false;           ///< Whether the client has successfully initialized its communication (by sending its magic and version)
 
         Client(QTcpSocket* socket);
     };
@@ -35 +45 @@
     explicit CurveDataServer();
     ~CurveDataServer();
 
+    /** Sends the current actuator position. */
     void sendActuatorPosition(float x, float y, float z);
+
+    /** Sends the actual direction the actuator is moving in. */
     void sendActualDirection(float x, float y, float z);
+
+    /** Sends the direction the actuator *should* be moving in, in order to draw the curve. */
     void sendTargetDirection(float x, float y, float z);
+
+    /** Stores and sends the specified curve. */
     void sendNewCurve(QList<QVector4D> &points);
+
+    /** Stores and sends the specified curve. */
     void sendNewCurve(QList<QVector3D> &points);
+
+    /** Sends the currently stored curve. This is used for newly connected clients. */
     void sendCurve(Client &client);
 
-    void processPings();            ///< send pings, check timeouts
+    /** Sends ping messages to the clients, checks whether any clients have timed out, and disconnects any that have. */
+    void processPings();
 
 public slots:
     void onNewConnection();
@@ -50 +72 @@
     void onReadyRead();
 
 private:
+    /** Gets the client that is connected via the specified socket. */
     QList<Client>::iterator clientOf(QTcpSocket *socket);
 
     void handleMessage(Client& client, uint16_t messageId, void* content);
@@ -58 +81 @@
     void handlePong(Client& client, uint64_t* content);
     void handleEOT(Client& client, char* content);
 
-    void validPreamble(Client& client);
     void removeSocket(QTcpSocket *socket);
     void terminateConnection(Client& client, std::string&& reason);
     void sendPing(Client& client);
@@ -75 +97 @@
     QTcpServer _server;
     std::thread _pingThread;
 
+    /**
+     * A flag that can be switched to `false` when the application should end, in order to gracefully stop the ping
+     * thread.
+     */
     volatile bool _threadIsRunning = true;
 
     std::recursive_mutex _socketsLock;