docs: implemented entire library headers docs (except exceptions)

Author: Alexandre jublot

include/Polymorph/Network/SerializerTrait.hpp

@@ -28,6 +28,11 @@ namespace polymorph::network
     struct SerializerTrait<T, true>
     {
 
+        /**
+         * @brief Serialize an standard type to byte array
+         * @param data standard type
+         * @return Vector of byte containing the byte representation of the object
+         */
         static std::vector<std::byte> serialize(const T &data)
         {
             std::vector<std::byte> buffer(sizeof(T));
@@ -36,6 +41,11 @@ namespace polymorph::network
             return buffer;
         }
 
+        /**
+         * @brief Deserialize a standard type to byte array
+         * @param data Vector of byte containing a representation of
+         * @return Vector of byte containing the byte representation of the object
+         */
         static T deserialize(const std::vector<std::byte> &buffer)
         {
             T dto;

include/Polymorph/Network/dto/ACKDto.hpp

@@ -15,9 +15,19 @@ namespace polymorph::network
 #ifdef _WIN32
 #pragma pack(push, 1)
 #endif
+    /**
+     * @struct Data transfer object for the ACK packet
+     */
     struct ACKDto
     {
+        /**
+         * @property The packet operation code
+         */
         static constexpr OpId opId = 1;
+
+        /**
+         * @property The packet identifier
+         */
         PacketId id;
     }
 #ifdef _WIN32

include/Polymorph/Network/dto/ConnectionDto.hpp

@@ -15,10 +15,24 @@ namespace polymorph::network
 #ifdef _WIN32
 #pragma pack(push, 1)
 #endif
+    /**
+     * @struct Data transfer object for the incoming connection packet
+     */
     struct ConnectionDto
     {
+        /**
+         * @property The packet operation code
+         */
         static constexpr OpId opId = 0;
+
+        /**
+         * @property The session identifier, used to identify the remote connection
+         */
         SessionId sessionId;
+
+        /**
+         * @property The authentication token, used as proof of identity
+         */
         AuthorizationKey authKey;
     }
 #ifdef _WIN32

include/Polymorph/Network/dto/ConnectionResponseDto.hpp

@@ -15,9 +15,22 @@ namespace polymorph::network
 #ifdef _WIN32
 #pragma pack(push, 1)
 #endif
+    /**
+     * @struct Data transfer object for responses to the incoming connection packet
+     */
     struct ConnectionResponseDto
     {
+        /**
+         * @property The packet operation code
+         */
         static constexpr OpId opId = 0;
+
+        /**
+         * @property The authentication status
+         *
+         * @return  true    if the connection was accepted and authenticated
+         * @return  false   if the connection was refused or the authentication failed
+         */
         bool authorized;
     }
 #ifdef _WIN32

include/Polymorph/Network/tcp/APacketHandler.hpp

@@ -19,6 +19,12 @@
 namespace polymorph::network::tcp
 {
 
+    /**
+     * @class   Base class for packet handlers
+     * @note    TCP exclusive
+     *
+     * @inherit IPacketHandler   The interface for packet handlers
+     */
     class APacketHandler : public IPacketHandler {
 
     ////////////////////// CONSTRUCTORS/DESTRUCTORS /////////////////////////
@@ -38,11 +44,23 @@ namespace polymorph::network::tcp
 
 
     private:
+        /**
+         * @property Map of the packet handlers, indexed by their operation code
+         *
+         * @return  std::map<OpId, std::function<void(const Packet&)>>    the map of the packet handlers
+         * @brief   The packet handlers are functions that will be called when a packet with the corresponding operation code is received
+         */
         std::map<polymorph::network::OpId,
             std::vector<std::function<bool(const PacketHeader &header, const std::vector<std::byte> &bytes)>>> _receiveCallbacks;
+        /**
+         * @property Thread that will handle the network operations (asio context)
+         */
         std::thread _thread;
 
     protected:
+        /**
+         * @property The asio context for the PacketHandler
+         */
         asio::io_context _context;
 
 
@@ -54,6 +72,12 @@ namespace polymorph::network::tcp
     public:
         bool packetReceived(const PacketHeader &, const std::vector<std::byte> &bytes) final;
 
+        /**
+         * @brief   Register the receive handler for the given operation code
+         *
+         * @param   opId    The operation code that will be associated with the receive handler function
+         * @param   handler The receive handler function
+         */
         template<typename T>
         void registerReceiveHandler(polymorph::network::OpId opId, std::function<bool(const PacketHeader &, const T &)> handler)
         {
@@ -62,9 +86,18 @@ namespace polymorph::network::tcp
                 return handler(header, packet.payload);
             });
         }
+
+        /**
+         * @brief   Unregister all the receive handlers for the given operation code
+         *
+         * @param   opId    The operation code that will be unregistered from the receive handlers
+         */
         void unregisterReceiveHandlers(polymorph::network::OpId opId);
 
     protected:
+        /**
+         * @brief   Run the asio context in a thread
+         */
         virtual void _run() final;
 
 

include/Polymorph/Network/tcp/Client.hpp

@@ -16,12 +16,22 @@
 namespace polymorph::network::tcp
 {
 
+    /**
+     * @class   TCP Client class
+     * @note    TCP exclusive
+     */
     class Client : public APacketHandler
     {
 
 ////////////////////// CONSTRUCTORS/DESTRUCTORS /////////////////////////
 
         public:
+            /**
+             * @brief   Constructor of the TCP Client class
+             *
+             * @param   host    The server host ip address
+             * @param   port    The server port
+             */
             Client(std::string host, std::uint16_t port);
 
             ~Client() override;
@@ -36,29 +46,77 @@ namespace polymorph::network::tcp
 
 
         private:
+            /**
+             * @property Client socket
+             */
             asio::ip::tcp::socket _socket;
-        asio::ip::tcp::endpoint _serverEndpoint;
 
+            /**
+             * @property Remote server endpoint
+             */
+            asio::ip::tcp::endpoint _serverEndpoint;
+
+            /**
+             * @property    The current packet being received
+             * @brief       Is used in the header of every packet to communicate the id of the packet
+             */
             PacketId _currentPacketId = 0;
+
+            /**
+             * @property    The current session id
+             * @brief       Is used in the header of every packet sent to communicate the session id
+             */
             SessionId _currentSession = 0;
+
+            /**
+             * @property    Atomic boolean to know if the client is connected
+             */
             std::atomic<bool> _isConnected = false;
+
+            /**
+             * @property    Atomic boolean to know if the client is connecting
+             */
             std::atomic<bool> _isConnecting = true;
 
+            /**
+             * @property    Queue of packets to send
+             */
             std::queue<std::pair<std::vector<std::byte>, std::function<void (const PacketHeader &, const std::vector<std::byte> &)>>> _sendQueue;
+
+            /**
+             * @property    Atomic boolean to know if the client is already sending a packet
+             */
             std::atomic<bool> _writeInProgress;
+
+            /**
+             * @property    Mutex to lock the send queue and ensure thread safety
+             */
             std::mutex _sendQueueMutex;
 
+            /**
+             * @property    Buffer to receive packets
+             */
             std::vector<std::byte> _receiveBuffer;
+
+            /**
+             * @property    Internal buffer to receive packets
+             */
             std::array<std::byte, 1024> _internalBuffer;
 
 
 
 //////////////////////--------------------------/////////////////////////
 
-
-
 /////////////////////////////// METHODS /////////////////////////////////
         public:
+            /**
+             * @brief   Send a payload to the server
+             *
+             * @tparam  T           The type of the payload to pack
+             * @param   opId        The operation id of the Packet
+             * @param   payload     The actual Packet data
+             * @param   callback    Callback function used when the data has been (or not) delivered
+             */
             template<typename T>
             void send(OpId opId, T &payload, std::function<void(const PacketHeader &, const T &)> callback = nullptr)
             {
@@ -86,16 +144,33 @@ namespace polymorph::network::tcp
                     _doSend();
                 }
             }
+
+            /**
+             * @brief   Connect to server and execute a callback when done
+             * @param   callback    Callback executed when the connection is done (or not)
+             * @note    bool of std::function correspond to the auth status (true = success, false otherwise)
+             */
             void connect(std::function<void(bool, SessionId)> callback);
 
+            /**
+             * @brief   Connect from a SessionId
+             * @note    This method is used to communicate with the server with a authenticated session
+             */
             void connectWithSession(SessionId session, AuthorizationKey authKey, std::function<void(bool, SessionId)> callback);
 
 
         private:
+            /**
+             * @brief   Method that use the queue to send packets
+             */
             void _doSend();
 
+            /**
+             * @brief   Method to handle the reception of a packet, deserialize it and call the callback
+             */
             void _doReceive();
 
+            // TODO: remove ?
             bool _broadcastReceivedPacket(const PacketHeader &header, const std::vector<std::byte> &bytes);
 
 

include/Polymorph/Network/tcp/ConnectionPool.hpp

@@ -16,6 +16,12 @@
 namespace polymorph::network::tcp
 {
 
+    /**
+     * @class   Base class for connection pools
+     * @note    TCP exclusive
+     *
+     * @inherit IConnectionPool    The interface for connection pools
+     */
     class ConnectionPool : public IConnectionPool
     {
 
@@ -36,7 +42,17 @@ namespace polymorph::network::tcp
 
 
         private:
+            /**
+             * @property The set of the connections
+             * @brief   The connections are stored in a set to avoid duplicates and fast access
+             *
+             * @return  std::set<Connection>    the set of the connections
+             */
             std::set<std::shared_ptr<IClientConnection>> _connections;
+
+            /**
+             * @property The mutex for the connections
+             */
             std::mutex _connectionsMutex;
 
 
@@ -50,8 +66,18 @@ namespace polymorph::network::tcp
 
             void leave(std::shared_ptr<IClientConnection> connection) override;
 
+            /**
+             * @brief   Get the connections
+             *
+             * @return  std::vector<Connection>    The connections stored in the pool
+             */
             std::vector<std::shared_ptr<IClientConnection>> getConnections();
 
+            /**
+             * @brief   Get the connections
+             *
+             * @return  std::vector<Connection>    The connections stored in the pool
+             */
             std::shared_ptr<IClientConnection> getConnectionBySessionId(SessionId id);
 
 

include/Polymorph/Network/tcp/IConnectionPool.hpp

@@ -10,16 +10,32 @@
 #include <memory>
 #include "Polymorph/Network/udp/IClientConnection.hpp"
 
-namespace polymorph::network::tcp {
+namespace polymorph::network::tcp
+{
+
     class ClientConnection;
 
+    /**
+     * @class   Interface for connection pools
+     * @note    TCP exclusive
+     */
     class IConnectionPool {
 
         public:
             virtual ~IConnectionPool() = default;
 
+            /**
+             * @brief   Add a connection to the pool
+             *
+             * @param   connection  The connection to add
+             */
             virtual void join(std::shared_ptr<IClientConnection> connection) = 0;
 
+            /**
+             * @brief   Remove a connection from the pool
+             *
+             * @param   connection  The connection to remove
+             */
             virtual void leave(std::shared_ptr<IClientConnection> connection) = 0;
 
     };