FIXED improved documentation

sdk/libraries/core/utils/InterfaceLogger.h

@@ -38,7 +38,7 @@ namespace camitk {
  * @ingroup group_sdk_libraries_core_utils
  *
  * @brief
- * The CamiTK Logger interface aims at tracing what happens during CamiTK-Applications 
+ * The CamiTK Logger interface aims at tracing what happens during CamiTK-Applications
  * process either on the standard output or on a file (or both).
  *
  * CamiTK Logger Interface assists CamiTK Developers to trace and check the execution flow of a CamiTK Application.
@@ -50,81 +50,81 @@ namespace camitk {
  *
  * This class defines an "interface" (in the OOP/java meaning of the term).
  * See the introduction of GoF: "Program to an interface, not an implementation."
+ *
+ * There are five level of verbosity:
+ * - NONE:    No messages are printed (whatever their degree of importance)
+ * - ERROR:   Only Error (i.e. messages logged using the log() function with the LogLevel ERROR) messages are printed
+ * - WARNING: Warning (i.e. messages logged using the log() function with the LogLevel WARNING)
+ *            and Error (i.e. messages logged using the log() function with the LogLevel ERROR) messages are both printed
+ * - INFO:    Info, Warning and Error messages are printed
+ * - TRACE:   All the messages logged thanks to the log() function, no matter their logLevel, are printed
  */
 
 class CAMITK_API InterfaceLogger {
 
 public:
-    /// Log Level: how chatty should the log output be...
+    /// @enum LogLevel: how chatty should the log output be... @see getLogLevel()
     enum LogLevel {
-        NONE    = 0,  /// No message is printed
-        ERROR   = 1,  /// Only error messages are printed
-        WARNING = 2,  /// Only Warning and Error messages are printed
-        INFO    = 3,
-        TRACE   = 4,
+        NONE    = 0,  ///< No message is logged
+        ERROR   = 1,  ///< Only error messages are logged
+        WARNING = 2,  ///< Only Warning and Error messages are logged
+        INFO    = 3,  ///< information, warning and error messages are logged
+        TRACE   = 4,  ///< all types of messages are logged
     };
 
     /// empty virtual destructor, to avoid memory leak
     virtual ~InterfaceLogger() {};
-    
-    /** Get Current verbosity level of the log:
-     * - NONE:    No message is printed (whatever their degree of importance)
-     * - ERROR:   Only Error (i.e. messages logged thanks to the log() function with the LogLevel ERROR) messages are printed
-     * - WARNING: Warning (i.e. messages logged thanks to the log() function with the LogLevel WARNING) 
-     *              and Error (i.e. messages logged thanks to the log() function with the LogLevel ERROR) messages are both printed
-     * - INFO:    Info, Warning and Error messages are printed
-     * - TRACE:   All the messages logged thanks to the log() function, no matter their logLevel, are printed
-     *
+
+    /** Get the current verbosity level of the log.
      */
     virtual LogLevel getLogLevel() = 0;
-    
-    /** Sets Current verbosity level of the log:
-     * - NONE:    No message is printed (whatever their degree of importance)
-     * - ERROR:   Only Error (i.e. messages logged thanks to the log() function with the LogLevel ERROR) messages are printed
-     * - WARNING: Warning (i.e. messages logged thanks to the log() function with the LogLevel WARNING)
-     *              and Error (i.e. messages logged thanks to the log() function with the LogLevel ERROR) messages are both printed
-     * - INFO:    Info, Warning and Error messages are printed
-     * - TRACE:   All the messages logged thanks to the log() function, no matter their logLevel, are printed
-     *
+
+    /** Sets Current verbosity level of the log.
      */
     virtual void setLogLevel(LogLevel level) = 0;
-    
+
     /** Allows the logger to write on std::cout
      */
     virtual void writeToStandardOutput(bool write) = 0;
-    
+
+    /** check if the logger is currently writing on standard output (std::cout)
+     *  @return true if the logger is currently writing on std output, false otherwise.
+     */
     virtual bool getWriteToStandardOutput() = 0;
-    
-    /** Gives the directory where to write the log file.
-     *  The file name will be determined by the logger
-     *  Returns true if the log file could have been created in the given directory, false otherwise.
+
+    /** Set the directory where to write the log file.
+     *  The file name will be determined by the logger.
+     *  @return true if the log file could have been created in the given directory, false otherwise.
      */
     virtual bool writeToDirectory(QString directoryName) = 0;
-    
+
+    /// @return the current path to the log file
+    /// TODO why not a QFileInfo ?
     virtual QString getLogFileFullPath() = 0;
-    
-    /** Allows to alert the user in case of errors or warning
+
+    /** Set the lowest log level that will open modal message box for messages instead
+     *  of (silently/undisruptedly) write on std output.
      *  Allows to debug thanks to message boxes.
-     *  Default value should be NONE (too anoying)
+     *  Default value is NONE (too annoying).
      */
     virtual void writeToMessageBoxLevel(LogLevel level) = 0;
-    
+
+    /// @return current log level that will generate modal message box
     virtual LogLevel getMessageBoxLevel() = 0;
 
     /** Log a message:
      *  If the logger is allowed to write on std::cout, it will display the message (and timestamp) on the standard output
      *  If the logger is allowed to write on a file, it will also display the message in the corresponding file...
      *
-     *  The parameter level referes to the message level to be compared with the logger level: 
-     *   if the logger level is greater than the message level (current level parameter), the current message will be printed.
+     *  The parameter level referes to the message level to be compared with the logger level:
+     *  if the logger level is greater or equals to the current log level, the current message will be printed.
      *
-     *  Example: if the logger level is at Warning, the messages of level Error and Warning will be displaied.
+     *  Example: if the logger level is at Warning, both Error and Warning level messages will be displayed.
      *
      */
-    virtual QString log(const QString msg, const LogLevel level, const QObject * sender) = 0;
-    
-
+    virtual QString log(const QString msg, const LogLevel level, const QObject* sender) = 0;
 };
+
 }
 
 #endif // INTERFACELOGGER_H