Added code documentation for server classes

Author: gabrieldiem

server_src/accepter.h

@@ -14,8 +14,17 @@ class Accepter: public Thread {
     ClientManager& clients;
 
 public:
+    /*
+     *   The Accepter is an active class (runs code in it's own thread)
+     *   It will accept new clients in a blocking manner (blocking it's own thread) and save the
+     * socket} in the ClientManager to add the client to the current connected clients.
+     */
     explicit Accepter(GameProtocolServer& server_protocol, ClientManager& clients);
 
+    /*
+     *   Method that the parent class Thread will run in it's own thread when calling
+     * Accepter::start. Contains the logic of the Accepter
+     */
     virtual void run() override;
 };
 

server_src/army.h

@@ -19,19 +19,42 @@ class Army {
     // cppcheck-suppress unusedStructMember
     std::vector<Enemy> army_vector;
 
+    /*
+     *  Updates the counters based on an enemy being just killed
+     */
     void kill_one_enemy();
 
+    /*
+     *  Updates the counters based on an enemy being just revived
+     */
     void revive_one_enemy();
 
+    /*
+     *  Notifies all the clients that a death has ocurred via the ClientManager
+     */
     void notify_death(ClientManager& clients);
 
+    /*
+     *  Notifies all the clients that a revival has ocurred via the ClientManager
+     */
     void notify_revival(ClientManager& clients);
 
 public:
+    /*
+     *  Army coordinates the logic to interact with the Enemies in an orderly manner
+     */
     explicit Army(uint16_t size);
 
+    /*
+     *  If there is at least one enemy alive, it kills them and notifies all the clients that a
+     * death has ocurred via the ClientManager
+     */
     const bool receive_attack(ClientManager& clients);
 
+    /*
+     *  Revives all the enemies fit for revival and notifies all the clients that a revival has
+     * ocurred via the ClientManager
+     */
     const uint16_t update_tick(ClientManager& clients);
 };
 

server_src/client_connection.h

@@ -21,39 +21,88 @@ class ClientConnection: public Thread {
     // cppcheck-suppress unusedStructMember
     bool has_finished_running;
 
+    /*
+     * ClientConnection stays with the ownership of the Socket until destruction
+     */
     Socket client_skt;
     GameProtocolServer& server_protocol;
 
     Queue<std::string>& client_commands_for_server;
-    Queue<GameMessage> messages_from_server;
 
     ClientConnectionReceiver receiver;
     ClientConnectionSender sender;
 
+    /*
+     * Each ClientConnection has it's own queue to be used in a blocking manner
+     * when keeping messages from the server to be sent to the destination client.
+     * It will block ClientConnectionSender's thread in the pop method
+     */
+    Queue<GameMessage> messages_from_server;
+
 
 public:
+    /*
+     *   The ClientConnection is an active class (runs code in it's own thread)
+     *   It will use it's class members ClientConnectionReceiver and ClientConnectionSender in order
+     * to connect with a client and send and receive in an async manner messages via the protocol
+     *
+     *   ClientConnectionReceiver and ClientConnectionSender are both active objects so the blocking
+     * does not affect ClientConnection's thread
+     */
     explicit ClientConnection(Socket&& client_skt, GameProtocolServer& server_protocol,
                               Queue<std::string>& client_commands_for_server);
 
+
+    /*
+     *  Disable copy constructor and asignment copy operator
+     *  ClientConnection is not meant to be copied
+     */
     ClientConnection(const ClientConnection&) = delete;
     ClientConnection& operator=(const ClientConnection&) = delete;
 
     /*
-     * Hacemos ClientConnection sea movible.
-     * */
+     *  Movement constructor and movement asignment operator are defined
+     */
     ClientConnection(ClientConnection&&);
     ClientConnection& operator=(ClientConnection&&);
 
+
+    /*
+     *   Method that the parent class Thread will run in it's own thread when calling
+     * ClientConnection::start. Starts it's members ClientConnectionReceiver and
+     * ClientConnectionSender
+     */
     virtual void run() override;
 
+    /*
+     *   Returns the unique randomly generated id of this ClientConnection
+     */
     const std::string get_client_id() const;
 
+    /*
+     *   It will push a message detailing an enemy's death to the
+     * ClientConnection::messages_from_server queue
+     */
     void notify_death(const uint16_t& enemies_alive, const uint16_t& enemies_dead);
 
+    /*
+     *   It will push a message detailing an enemy's revival to the
+     * ClientConnection::messages_from_server queue
+     */
     void notify_revival(const uint16_t& enemies_alive, const uint16_t& enemies_dead);
 
+    /*
+     *   It will kill this ClientConnection
+     *   After executing this method the ClientConnection will be no longer be able to be used
+     *   It will shutdown the socket connection and join the ClientConnectionReceiver and
+     * ClientConnectionSender threads into the ClientConnection's thread
+     */
     void kill();
 
+    /*
+     *   Joins ClientConnectionReceiver and ClientConnectionSender threads into ClientConnection's
+     * thread if they were not joined before and shutdowns the socket connection it it's still open
+     */
     ~ClientConnection();
 };
 

server_src/client_connection_receiver.h

@@ -18,10 +18,20 @@ class ClientConnectionReceiver: public Thread {
     Queue<std::string>& client_commands_for_server;
 
 public:
+    /*
+     *   The ClientConnectionReceiver is an active class (runs code in it's own thread)
+     *   It will use the Socket via the GameProtocolServer in order to receive command messages and
+     * push them in a blocking manner into the client_commands_for_server queue, blocking it's own
+     * thread in the receive part of the Socket communication
+     */
     explicit ClientConnectionReceiver(const std::string& client_id, Socket& skt,
                                       GameProtocolServer& server_protocol,
                                       Queue<std::string>& client_commands_for_server);
-
+    /*
+     *   Method that the parent class Thread will run in it's own thread when calling
+     * ClientConnectionReceiver::start. Contains the logic of the ClientConnectionReceiver.
+     * It will stop receiving if the socket connection is shutdown.
+     */
     virtual void run() override;
 };
 

server_src/client_connection_sender.h

@@ -18,10 +18,21 @@ class ClientConnectionSender: public Thread {
     Queue<GameMessage>& messages_from_server;
 
 public:
+    /*
+     *   The ClientConnectionSender is an active class (runs code in it's own thread)
+     *   It will use the Socket via the GameProtocolServer in order to send command messages after
+     * being poped in a blocking manner from the messages_from_server queue, blocking it's own
+     * thread in the pop part of the process
+     */
     explicit ClientConnectionSender(const std::string& client_id, Socket& skt,
                                     GameProtocolServer& server_protocol,
                                     Queue<GameMessage>& messages_from_server);
-
+    /*
+     *   Method that the parent class Thread will run in it's own thread when calling
+     * ClientConnectionSender::start. Contains the logic of the ClientConnectionSender.
+     * It will stop sending if the socket connection is shutdown or if the messages_from_server
+     * queue is closed
+     */
     virtual void run() override;
 };
 

server_src/client_manager.h

@@ -20,18 +20,53 @@ class ClientManager {
     std::mutex mutex;
 
 public:
+    /*
+     * ClientManager is a class of type Monitor
+     * It handles the access to the clients of type ClientConnection, given that the clients are
+     * active objects and are running code in their own threads
+     *
+     * It's also the single entry point for the ClientManager::client_commands_queue queue, that
+     * keeps all the messages received from all the clients
+     */
     explicit ClientManager(GameProtocolServer& server_protocol);
 
+    /*
+     *   Receives the ownership of a Socket to give it to a newly created ClientConnection and then
+     * save it in  the vector ClientManager::clients as a heap allocated object
+     */
     void add_client(Socket&& new_client_skt);
+
+    /*
+     *   Returns the number of connections currently stored
+     */
     const uint16_t current_connections();
-    const bool try_next_command(std::string& next_cmd);
 
-    void notify_all(const uint16_t& just_died, const uint16_t& just_revived);
+    /*
+     *   Performs a non-blocking pop onto the ClientManager::client_commands_queue queue
+     */
+    const bool try_next_command(std::string& next_cmd);
 
+    /*
+     *   Sends an enemy death event to each connected client and prints that event to std::out
+     */
     void notify_death_all(const uint16_t enemies_alive, const uint16_t enemies_dead);
+
+    /*
+     *   Sends an enemy revival event to each connected client and prints that event to std::out
+     */
     void notify_revival_all(const uint16_t enemies_alive, const uint16_t enemies_dead);
 
+    /*
+     *   It will kill all the ClientConnections
+     *   After executing this method the ClientConnections will be no longer be able to be used
+     *   It will shutdown the sockets connections and join the all the ClientConnection threads into
+     * the ClientManager's thread
+     */
     void kill_all();
+
+    /*
+     *   Frees all the heap allocated memory for the ClientConnections
+     */
     ~ClientManager();
 };
 

server_src/enemy.h

@@ -12,17 +12,38 @@ class Enemy {
     // cppcheck-suppress unusedStructMember
     uint32_t ticks_until_revived;
 
+    /*
+     *   Returns true if the enemy is dead has already reached Enemy::TICKS_FOR_REVIVAL ticks dead
+     */
     const bool should_revive() const;
 
+    /*
+     *   Revives the enemy and makes it fit for being attacked
+     */
     void revive();
 
 public:
+    /*
+     *   Encapsulates the logic and inner workings of an enemy
+     *   Enemy::TICKS_FOR_REVIVAL defines the number of ticks needed for an enemy to revive
+     *   after being killed
+     */
     Enemy();
 
+    /*
+     *   Returns true is the enemy is alive
+     */
     const bool is_alive() const;
 
+    /*
+     *   Performs the logic for receiving an attack. Killing the enemy and starting the revival
+     * process
+     */
     const bool receive_attack();
 
+    /*
+     *   Performs the updated expected for each tick. Updates the progress of revival
+     */
     const bool update_tick();
 };
 

server_src/game_protocol_server.h

@@ -31,10 +31,11 @@ class GameProtocolServer {
      *  serialization of data and the socket communication. It should be paired at the other end
      *  with a GameProtocolClient
      *
-     *  For GameProtocolServer to be fully constructed it will wait for an inbound socket
-     * connection. This means that until a client connects, this class will not be fully
-     * constructed. A GameProtocolServer already instantiated object naturally means it has
-     * previously established a connection with a client
+     *  It has the ownership of the main socket of the server
+     *  It serves as a translation layer for other classes that has ownership of their own sockets
+     *
+     *  A mutex is used to ensure that a race condition is not possible when reading the state of
+     * the main socket
      */
     explicit GameProtocolServer(const std::string& servname);
 
@@ -53,42 +54,63 @@ class GameProtocolServer {
     GameProtocolServer& operator=(GameProtocolServer&&) = default;
 
     /*
-     *  Receives action codes from inbound_client until the end_of_sequence action code is sent
+     *  Returns the Socket of an accepted connection to the main server socket
      */
-    // const std::vector<std::string> get_action_sequence();
+    Socket accept_client();
 
     /*
-     *  Returns true if the connection with the inbound_client is still alive. Return false
-     *  if it has closed
+     *  Returns true if the main server socket is closed or false otherwise
      */
-    // const bool is_client_connection_alive() const;
+    const bool is_socket_closed();
 
     /*
-     *  Sends to inbound_client as a halfword (2 bytes) the header of the payload (size of the
-     *  payload) and then sends bytewise the payload (binary representation of a string)
+     *  Returns true if the input command string is an attack command, returns false otherwise
      */
-    // void send_action_sequence_with_combos(const std::string& combo_response);
-
-    Socket accept_client();
-
-    const bool is_socket_closed();
-
     const bool is_command_attack(const std::string& command) const;
 
+    /*
+     *  Builds and returns a GameMessage that represents a death event with the corresponding
+     * parameters
+     */
     const GameMessage get_message_for_death_event(const uint16_t enemies_alive,
                                                   const uint16_t enemies_dead) const;
 
+    /*
+     *  Builds and returns a GameMessage that represents a revival event with the corresponding
+     * parameters
+     */
     const GameMessage get_message_for_revival_event(const uint16_t enemies_alive,
                                                     const uint16_t enemies_dead) const;
 
+    /*
+     *  Sends a complete message to the client. First a byte for signaling the beginning of the
+     * broadcast then it sends 2 halfwords (each one of 2 bytes) representing the number of enemies
+     * alive and dead, in that order, and finally it sends a byte for signaling if an enemy has been
+     * killed or has revived
+     */
     void send_message_to_client(Socket& client_skt, const GameMessage& message, bool& was_closed);
 
+    /*
+     *  Receives a byte from the client_skt that represents the desired command. Returns that
+     * command name
+     */
     const std::string receive_message_from_client(Socket& client_skt, bool& was_closed);
 
+    /*
+     *  Prints to std::out the current death event with the number of enemies alive and dead
+     * represented by the params
+     */
     void print_death_in_server(const uint16_t& enemies_alive, const uint16_t& enemies_dead) const;
 
+    /*
+     *  Prints to std::out the current revival event with the number of enemies alive and dead
+     * represented by the params
+     */
     void print_revival_in_server(const uint16_t& enemies_alive, const uint16_t& enemies_dead) const;
 
+    /*
+     *  Shutdowns and closes the main server socket
+     */
     void turn_off_connections();
 };