From 7d706b122d7eb1ba14bc52cb4881b927cb01473f Mon Sep 17 00:00:00 2001
From: Cerapter <cerap@protonmail.com>
Date: Mon, 15 Mar 2021 15:29:03 +0100
Subject: [PATCH] Document WSClient

---
 include/ws_client.h | 67 ++++++++++++++++++++++++++++++++++++++++++++-
 include/ws_proxy.h  |  2 +-
 src/ws_client.cpp   |  7 -----
 3 files changed, 67 insertions(+), 9 deletions(-)

diff --git a/include/ws_client.h b/include/ws_client.h
index 7c824bc..f5b1d96 100644
--- a/include/ws_client.h
+++ b/include/ws_client.h
@@ -23,21 +23,86 @@
 #include <QTcpSocket>
 #include <QString>
 
+/**
+ * @brief Represents a WebSocket client (generally WebAO) connected to the server.
+ *
+ * @details To give a common interface to both desktop AO and WebAO clients, the incoming data from
+ * WebSocket connections are directed through local TCP sockets.
+ *
+ * This class is a very thin layer -- see WSProxy for the actual mechanics of this WebSocket-to-TCP proxy solution.
+ */
 class WSClient : public QObject {
     Q_OBJECT
 public:
-    WSClient(QTcpSocket* p_tcp_socket, QWebSocket* p_web_socket, QObject* parent = nullptr);
+    /**
+     * @brief Creates an instance of the WSClient class.
+     *
+     * @param p_tcp_socket The locally created TCP socket to direct data through.
+     * @param p_web_socket The WebSocket that actually represents the connecting client.
+     * @param parent Qt-based parent, passed along to inherited constructor from QObject.
+     *
+     * @pre This class will not connect up the ports to each other in any way. Unless some setup is done, this class
+     * by default will never be prompted to read and/or write from/to either of the sockets.
+     */
+    WSClient(QTcpSocket* p_tcp_socket, QWebSocket* p_web_socket, QObject* parent = nullptr)
+        : QObject(parent), tcp_socket(p_tcp_socket), web_socket(p_web_socket) {};
+
+    /**
+      * @brief Destructor for the WSClient class.
+      *
+      * @details Marks the TCP and WebSocket for later deletion.
+      */
     ~WSClient();
 public slots:
+    /**
+     * @brief A slot that can be signalled when #tcp_socket has data ready for reading.
+     * Will read all data in the socket.
+     *
+     * @details The incoming data is separated per-packet due to the WebAO bug, and the packets are sent
+     * through #web_socket.
+     */
     void onTcpData();
+
+    /**
+     * @brief A slot that can be signalled to push packets received from WebSocket into the
+     * associated local TCP socket.
+     *
+     * @param message The incoming packet.
+     */
     void onWsData(QString message);
+
+    /**
+     * @brief A slot that can be signalled when the WebSocket client disconnect.
+     * Disconnects the associated TCP socket.
+     *
+     * @see onTcpDisconnect() for the opposite scenario.
+     */
     void onWsDisconnect();
+
+    /**
+     * @brief A slot that can be signalled when the TCP socket is disconnected.
+     * Severs the connection to the WebSocket.
+     *
+     * @see onWsDisconnect() for the opposite scenario.
+     */
     void onTcpDisconnect();
+
+    /**
+     * @brief A slot that can be signalled when the TCP socket is connected.
+     * Sends identification over the socket.
+     */
     void onTcpConnect();
 
 
 private:
+    /**
+     * @brief The local TCP socket used as a proxy to connect with the server.
+     */
     QTcpSocket* tcp_socket;
+
+    /**
+     * @brief The WebSocket representing an incoming connection.
+     */
     QWebSocket* web_socket;
 };
 
diff --git a/include/ws_proxy.h b/include/ws_proxy.h
index a808b77..d83bed3 100644
--- a/include/ws_proxy.h
+++ b/include/ws_proxy.h
@@ -38,7 +38,7 @@ class WSProxy : public QObject {
      * @param p_local_port The port through which the TCP connection should be directed. Should the same as with
      * non-WebAO connections.
      * @param p_ws_port The WebSocket port. Should the same that is opened for WebSockets connections.
-     * @param p_parent Qt-based parent, passed along to inherited constructor from QObject.
+     * @param parent Qt-based parent, passed along to inherited constructor from QObject.
      */
     WSProxy(int p_local_port, int p_ws_port, QObject* parent);
 
diff --git a/src/ws_client.cpp b/src/ws_client.cpp
index 7865fb0..e74c65a 100644
--- a/src/ws_client.cpp
+++ b/src/ws_client.cpp
@@ -17,13 +17,6 @@
 //////////////////////////////////////////////////////////////////////////////////////
 #include "include/ws_client.h"
 
-WSClient::WSClient(QTcpSocket* p_tcp_socket, QWebSocket* p_web_socket, QObject* parent)
-    : QObject(parent)
-{
-    tcp_socket = p_tcp_socket;
-    web_socket = p_web_socket;
-}
-
 void WSClient::onWsData(QString message)
 {
     tcp_socket->write(message.toUtf8());