Logger api documentation

Author: florianbecker

source/FileLogger.h

@@ -34,6 +34,7 @@
 #include <chrono>
 #include <fstream>
 #include <string>
+#include <unordered_map>
 
 /* local header */
 #include "Logger.h"
@@ -43,25 +44,62 @@
  */
 namespace vx {
 
-  /* logger that writes to file */
+  /**
+   * @brief The FileLogger class for writing messages to file.
+   * @author Florian Becker <fb\@vxapps.com> (VX APPS)
+   */
   class FileLogger : public Logger {
 
   public:
+    /**
+     * @brief Deletet default constructor for FileLogger.
+     */
     FileLogger() = delete;
 
+    /**
+     * @brief Default constructor for FileLogger.
+     * @param _configuration   Logger configuration.
+     */
     explicit FileLogger( const std::unordered_map<std::string, std::string> &_config );
 
+    /**
+     * @brief Build the log message.
+     * @param _message   Message to log.
+     * @param _severity   Severity level of the message.
+     */
     virtual void log( const std::string &_message, const Severity _severity ) override;
 
+    /**
+     * @brief Output the log message.
+     * @param _message   Message to log.
+     */
     virtual void log( const std::string &_message ) override;
 
   protected:
+    /**
+     * @brief Close and reopen the log file.
+     */
     void reopen();
 
   private:
+    /**
+     * @brief Log filename.
+     */
     std::string m_filename;
+
+    /**
+     * @brief Log file handle.
+     */
     std::ofstream m_file;
+
+    /**
+     * @brief Interval for reopening the log file.
+     */
     std::chrono::seconds m_reopenInterval;
+
+    /**
+     * @brief Timestamp of last reopen activity.
+     */
     std::chrono::system_clock::time_point m_lastReopen;
   };
 }

source/Logger.h

@@ -33,7 +33,6 @@
 /* stl header */
 #include <chrono>
 #include <iomanip>
-#include <mutex>
 #include <sstream>
 #include <string>
 #include <unordered_map>
@@ -43,18 +42,19 @@
  */
 namespace vx {
 
-  /* the log levels we support */
+  /**
+   * @brief The Severity enum.
+   */
   enum class Severity {
 
-    Verbose,
-    Debug,
-    Info,
-    Warning,
-    Error,
-    Fatal
+    Verbose, /**< Verbose level. */
+    Debug, /**< Debug level. */
+    Info, /**< Info level. */
+    Warning, /**< Warning level. */
+    Error, /**< Error level. */
+    Fatal /**< Fatal error level. */
   };
 
-  /* all, something in between, none or default to info */
 #if defined(LOGGINGALL) || defined(LOGGINGVERBOSE)
   constexpr Severity avoidLogAbove = Severity::Verbose;
 #elif defined(LOGGINGDEBUG)
@@ -71,7 +71,10 @@ namespace vx {
   constexpr Severity avoidLogAbove = Severity::Info;
 #endif
 
-  /* returns formated to: 'Y-m-dTh:m:s.xxxxxx' */
+  /**
+   * @brief Create thread-safe timestamp.
+   * @return Timestamp as 'Y-m-dThh:mm:ss.xxxxxx'
+   */
   inline std::string timestamp() {
 
     /* get a precise timestamp as a string */
@@ -97,23 +100,51 @@ namespace vx {
     return result;
   }
 
-  inline std::string threadId() {
+  // TODO: Currently not used
+/*  inline std::string threadId() {
 
     std::ostringstream s;
     s << " [" << std::this_thread::get_id() << "]";
     s.flush();
     std::string result = s.str();
     return result;
-  }
+  } */
 
-  /* logger base class, not pure virtual so you can use as a null logger if you want */
+  /**
+   * @brief The Logger class.
+   * @note Not pure virtual to use as /dev/null logger.
+   * @author Florian Becker <fb\@vxapps.com> (VX APPS)
+   */
   class Logger {
 
   public:
+    /**
+     * @brief Deletet default constructor for Logger.
+     */
     Logger() = delete;
+
+    /**
+     * @brief Default constructor for Logger.
+     * @param _configuration   Logger configuration.
+     */
     explicit Logger( const std::unordered_map<std::string, std::string> &_configuration );
+
+    /**
+     * @brief Default destructor for Logger.
+     */
     virtual ~Logger() = default;
+
+    /**
+     * @brief Build the log message.
+     * @param _message   Message to log.
+     * @param _severity   Severity level of the message.
+     */
     virtual void log( const std::string &_message, const Severity _severity );
+
+    /**
+     * @brief Output the log message.
+     * @param _message   Message to log.
+     */
     virtual void log( const std::string &_message );
   };
 }

source/LoggerFactory.h

@@ -45,70 +45,119 @@
  */
 namespace vx {
 
-  /* a factory that can create loggers (that derive from 'logger') via function pointers */
-  /* this way you could make your own logger that sends log messages to who knows where */
+  /**
+   * @brief The LoggerFactory class.
+   * @author Florian Becker <fb\@vxapps.com> (VX APPS)
+   */
   class LoggerFactory : public Singleton<LoggerFactory> {
 
   public:
+    /**
+     * @brief Default constructor for LoggerFactory.
+     */
     explicit LoggerFactory();
 
+    /**
+     * @brief Create all siblings of different log possibilities.
+     * @param _config   Configuration for logger.
+     * @return Logger class with specific config.
+     */
     Logger *produce( const std::unordered_map<std::string, std::string> &_config ) const;
 
   private:
+    /**
+     * @brief Created loggers.
+     */
     std::unordered_map<std::string, Logger *( * )( const std::unordered_map<std::string, std::string> & )> m_creators;
   };
 
-  /* get at the singleton */
+  /**
+   * @brief Create instance with default configuration for logger.
+   * @param _config   Configuration for logger.
+   */
   inline Logger &instance( const std::unordered_map<std::string, std::string> &_config = { { "type", "std" }, { "color", "" } } ) {
 
     static std::unique_ptr<Logger> singleton( LoggerFactory::instance().produce( _config ) );
     return *singleton;
   }
 
-  /* configure the singleton (once only) */
+  /**
+   * @brief Change the configuration at runtime.
+   * @param _config   Logger configuration.
+   */
   inline void LogConfigure( const std::unordered_map<std::string, std::string> &_config ) {
 
     instance( _config );
   }
 
-  /* statically log manually without the macros below */
-  inline void Log( const std::string &_message, const Severity _level ) {
+  /**
+   * @brief Direct function for logging.
+   * @param _message   Message to log.
+   * @param _severity   Severity level for message to log.
+   */
+  inline void Log( const std::string &_message, const Severity _severity ) {
 
-    instance().log( _message, _level );
+    instance().log( _message, _severity );
   }
 
-  /* statically log manually without a level or maybe with a custom one */
+  /**
+   * @brief Direct function for logging.
+   * @param _message   Message to log.
+   */
   inline void Log( const std::string &_message ) {
 
     instance().log( _message );
   }
 
-  /* these standout when reading code */
+  /**
+   * @brief Direct function for logging with verbose serivity.
+   * @param _message   Message to log.
+   */
   inline void LogVerbose( const std::string &_message ) {
 
     instance().log( _message, Severity::Verbose );
   };
 
+  /**
+   * @brief Direct function for logging with debug serivity.
+   * @param _message   Message to log.
+   */
   inline void LogDebug( const std::string &_message ) {
 
     instance().log( _message, Severity::Debug );
   };
 
+  /**
+   * @brief Direct function for logging with info serivity.
+   * @param _message   Message to log.
+   */
   inline void LogInfo( const std::string &_message ) {
 
     instance().log( _message, Severity::Info );
   };
 
+  /**
+   * @brief Direct function for logging with warning serivity.
+   * @param _message   Message to log.
+   */
   inline void LogWarning( const std::string &_message ) {
 
     instance().log( _message, Severity::Warning );
   };
 
+  /**
+   * @brief Direct function for logging with error serivity.
+   * @param _message   Message to log.
+   */
   inline void LogError( const std::string &_message ) {
 
     instance().log( _message, Severity::Error );
   };
 
+  /**
+   * @brief Direct function for logging with fatal error serivity.
+   * @param _message   Message to log.
+   */
   inline void LogFatal( const std::string &_message ) {
 
     instance().log( _message, Severity::Fatal );

source/StdLogger.h

@@ -42,19 +42,46 @@
  */
 namespace vx {
 
-  /* logger that writes to standard out */
+  /**
+   * @brief The StdLogger class for writing messages to stdout.
+   * @author Florian Becker <fb\@vxapps.com> (VX APPS)
+   */
   class StdLogger : public Logger {
 
   public:
+    /**
+     * @brief Deletet default constructor for StdLogger.
+     */
     StdLogger() = delete;
+
+    /**
+     * @brief Default constructor for StdLogger.
+     * @param _configuration   Logger configuration.
+     */
     explicit StdLogger( const std::unordered_map<std::string, std::string> &_config );
 
+    /**
+     * @brief Build the log message.
+     * @param _message   Message to log.
+     * @param _severity   Severity level of the message.
+     */
     virtual void log( const std::string &m_message, const Severity _severity ) override;
 
+    /**
+     * @brief Output the log message.
+     * @param _message   Message to log.
+     */
     virtual void log( const std::string &_message ) override;
 
   private:
+    /**
+     * @brief Use colored message output.
+     */
     bool m_useColor = false;
+
+    /**
+     * @brief Use stderr for severity >= Error.
+     */
     bool m_useStdErr = false;
   };
 }