Added code documentation for common classes

Author: gabrieldiem

common_src/closed_queue.h

@@ -5,6 +5,9 @@
 
 class ClosedQueue: public std::runtime_error {
 public:
+    /*
+     *   Exception that indicates when a Queue is closed and an operation was performed over it
+     */
     explicit ClosedQueue(const int line_number);
 };
 

common_src/game_commands.h

@@ -24,19 +24,34 @@ class GameCommands {
      */
     GameCommands();
 
+    /*
+     *  Returns the command code that represents an attack
+     */
     const uint8_t get_client_attack_code() const;
 
+    /*
+     *  Returns the command code that represents the beginning of the server broadcast
+     */
     const uint8_t get_server_start_broadcast_code() const;
 
+    /*
+     *  Returns the command code that represents an enemy death
+     */
     const uint8_t get_enemy_died_code() const;
 
+    /*
+     *  Returns the command code that represents an enemy revival
+     */
     const uint8_t get_enemy_revived_code() const;
 
     /*
-     *  Returns the action name for a given action by its code
+     *  Returns the command name for a given command by its code
      */
-    const std::string get_key_from_code(const uint8_t& action_code) const;
+    const std::string get_key_from_code(const uint8_t& cmd_code) const;
 
+    /*
+     *  Returns the command code for a given command by its name
+     */
     const uint8_t get_code_from_key(const std::string& cmd_key) const;
 };
 

common_src/game_message.h

@@ -14,13 +14,25 @@ class GameMessage {
     const std::string enemy_event;
 
 public:
+    /*
+     *   GameMessage encapsulates essential information for both server and client messages
+     */
     explicit GameMessage(const uint16_t& enemies_alive, const uint16_t& enemies_dead,
                          const std::string& enemy_event);
 
+    /*
+     *   Returns the number of enemies alive at the time of the creation of the message
+     */
     const uint16_t get_enemies_alive() const;
 
+    /*
+     *   Returns the number of enemies dead at the time of the creation of the message
+     */
     const uint16_t get_enemies_dead() const;
 
+    /*
+     *   Returns the string representation of the enemy event, it can be a revival or death event
+     */
     const std::string get_enemy_event() const;
 };
 

common_src/jazz_jackrabbit_2_error.h

@@ -14,6 +14,12 @@ class JazzJackrabbit2Error: public std::exception {
     std::string final_message;
 
 public:
+    /*
+     *   Custom exception created to be used throught the game, both in the server and in the
+     * client. It's an upgrade from a regular std::exception because it carries the line number
+     * (__LINE__) and module name  (__FILE__) where the exception was thrown, this has to be filled
+     * at the time of instantiation by the caller
+     */
     JazzJackrabbit2Error(const std::string& base_message, const int32_t& line_number,
                          const std::string& module);
 

common_src/logger.h

@@ -25,40 +25,92 @@ class Logger {
     bool is_activated;
 
     /*
-     *  Logger description. Private constructor to prevent instantiation.
+     *   A mutex is used to ensure the logfile will be accessed by one thread at a time
+     */
+    std::mutex mutex;
+
+    /*
+     *  Logger that logs events to a file. It can be used both in the server and in the client with
+     * their respective methods. It is built using the Singleton pattern. This way we use a single
+     * logger throughout the process. That is why the constructor is hidden and the instance can be
+     * accessed with the Logger::get_instance static method
      */
     Logger();
 
     /*
-     *  Delete copy constructor. Delete assignment operator.
+     *  Delete copy constructor and copy assignment operator.
      */
     Logger(const Logger&) = delete;
     Logger& operator=(const Logger&) = delete;
 
+    /*
+     *  Delete move constructor and move assignment operator.
+     */
+    Logger(const Logger&&) = delete;
+    Logger& operator=(const Logger&&) = delete;
 
+    /*
+     *  Closes the logfile
+     */
     void close();
 
+    /*
+     *  Returns current time with the format defined by Logger::time_format
+     */
     const std::string get_current_time();
 
+    /*
+     *  Writes in the file the logging output using the time format, the message and the log level
+     */
     void log(const std::string& log_level, const std::string& message);
 
-    std::mutex mutex;
 
 public:
+    /*
+     *  Uses the Singleton design pattern
+     *   Return the instance
+     */
     static Logger& get_instance();
 
+    /*
+     *  It's a client method, so the log line will include the CLIENT keyword
+     *  Logs the message with log level Logger::LEVEL_INFO
+     */
     void client_info(const std::string& message);
 
+    /*
+     *  It's a client method, so the log line will include the CLIENT keyword
+     *  Logs the message with log level Logger::LEVEL_WARNING
+     */
     void client_warning(const std::string& message);
 
+    /*
+     *  It's a client method, so the log line will include the CLIENT keyword
+     *  Logs the message with log level Logger::LEVEL_ERROR
+     */
     void client_error(const std::string& message);
 
+    /*
+     *  It's a server method, so the log line will include the SERVER keyword
+     *  Logs the message with log level Logger::LEVEL_INFO
+     */
     void server_info(const std::string& message);
 
+    /*
+     *  It's a server method, so the log line will include the SERVER keyword
+     *  Logs the message with log level Logger::LEVEL_WARNING
+     */
     void server_warning(const std::string& message);
 
+    /*
+     *  It's a server method, so the log line will include the SERVER keyword
+     *  Logs the message with log level Logger::LEVEL_ERROR
+     */
     void server_error(const std::string& message);
 
+    /*
+     *  Closes the file before destroying member variables
+     */
     ~Logger();
 };
 

common_src/thread.h

@@ -43,4 +43,4 @@ class Thread: public Runnable {
     Thread& operator=(Thread&& other) = delete;
 };
 
-#endif
+#endif  // THREAD_H_