[doc] Improve documentation on logger and real-time-logger

Mostly give a sample on how to use the logger member inside the entities.

Author: olivier-stasse

doc/additionalDoc/debug-doc.h

@@ -2,9 +2,14 @@
 \page debug Debugging
 
 They are several ways to perform debugging in dynamic-graph depending on your needs or situation:
+- Programmatically inside the entity in C++ will write inside a buffer in a different thread and output in a stream
+(either std::cout or a file). It is detailed in \subpage subp_debug_rt_logger.
+- Programmatically inside the entity in C++ using a member of the entities and the previous real-time mechanism. 
+It provides 4 levels of messags :(DEBUG,INFO, WARNING, ERROR). It is described in details here:
+\subpage subp_logger
+- Programmatically in C++ to avoid overhead with macros and handling level as an int: \subpage subp_dbg_trace
 - If you just need to collect informations from signals (like rosbag). You can use
-an entity called Tracer inside the graph:\subpage tracerdoc
-- programmatically in C++ with macros \subpage subp_dbg_trace
-- programmatically inside the entity in C++ using member of the entities:
-\subpage tracerrealtimedoc
+an entity called Tracer inside the graph:\subpage tracerdoc . <br>
+A real time version exists
+to write directly inside a memory buffer \subpage tracerrealtimedoc
 **/

doc/additionalDoc/debug-logger.h

@@ -0,0 +1,68 @@
+/** 
+\page subp_logger Loggers
+
+\section sec_logger Initialization of the logger
+
+\subsection subsec_logger_hcpp Header and preprocessor variable
+
+In order to activate the logger you need to add the following lines:
+\code
+#define ENABLE_RT_LOG
+#include <dynamic-graph/real-time-logger.h>
+#include <dynamic-graph/logger.h>
+\endcode
+
+\subsection subsec_logger_ Initialize the output stream
+
+It is possible to set the output stream of the messages inside a file:
+\code
+  dynamicgraph::RealTimeLogger::instance();
+  of.open("/tmp/dg-LOGS.txt",std::ofstream::out|std::ofstream::app); 
+  dgADD_OSTREAM_TO_RTLOG (of);
+  
+  dynamicgraph::RealTimeLogger::destroy();
+\endcode
+Here the file is "/tmp/dg-LOGS.txt". 
+
+\subsection subsec_logger_init Initialization of the logger
+
+Inside the constructor of the entity:
+\code
+      logger_.setTimeSample(0.001);
+      logger_.setStreamPrintPeriod(0.005);
+      logger_.setVerbosity(VERBOSITY_ALL);
+      LoggerVerbosity alv = logger_.getVerbosity();
+\endcode
+
+The first line sets the frequency at which the logger will be updated.<br>
+The second line specifies at which frequency the message should be
+printed.<br>
+The third line specifies the level of message to accept.<br>
+The fourth line returns the level of verbosity.
+In this case, all messages are accepted. <br>
+
+The full list of options are:
+<ul>
+<li>VERBOSITY_ALL: Accept all messages</li>
+<li>VERBOSITY_INFO_WARNING_ERROR: Accept messages at minimum level : INFO, WARNING, ERROR</li>
+<li>VERBOSITY_WARNING_ERROR: Accept messages at minimum level : WARNING, ERROR</li>
+<li>VERBOSITY_ERROR: Accept messages at minimum level : ERROR</li>
+</ul>
+
+
+\section sec_logger_tests Displaying messages
+
+Here is some example on how to display or record some information.
+\code
+      sendMsg("This is a message of level MSG_TYPE_DEBUG",MSG_TYPE_DEBUG);
+      sendMsg("This is a message of level MSG_TYPE_INFO",MSG_TYPE_INFO);
+      sendMsg("This is a message of level MSG_TYPE_WARNING",MSG_TYPE_WARNING);
+      sendMsg("This is a message of level MSG_TYPE_ERROR",MSG_TYPE_ERROR);
+      sendMsg("This is a message of level MSG_TYPE_DEBUG_STREAM",MSG_TYPE_DEBUG_STREAM);
+      sendMsg("This is a message of level MSG_TYPE_INFO_STREAM",MSG_TYPE_INFO_STREAM);
+      sendMsg("This is a message of level MSG_TYPE_WARNING_STREAM",MSG_TYPE_WARNING_STREAM);
+      sendMsg("This is a message of level MSG_TYPE_ERROR_STREAM",MSG_TYPE_ERROR_STREAM);
+
+      logger_.countdown();
+\endcode
+*/

doc/additionalDoc/debug-real-time-logger.h

@@ -0,0 +1,22 @@
+/**  
+\page subp_debug_rt_logger Real-time Logger
+
+ It is intended to be used like this:
+   \code
+   #define ENABLE_RT_LOG
+   #include <dynamic-graph/real-time-logger.h>
+  
+   // Somewhere in the main function of your executable
+   int main (int argc, char** argv) {
+     dgADD_OSTREAM_TO_RTLOG (std::cout);
+   }
+  
+   // Somewhere in your library
+   dgRTLOG() << "your message. Prefer to use \n than std::endl."
+   \endcode
+  
+   \note Thread safety. This class expects to have:
+   - only one reader: the one who take the log entries and write them somewhere.
+   - one writer at a time. Writing to the logs is **never** a blocking
+     operation. If the resource is busy, the log entry is discarded.
+*/