doxygen: Document logging

diff --git a/src/doxygen-mainpage.h b/src/doxygen-mainpage.h
index 40528595dfc8ebee661d65051be10d2d89ca52a1..3442f03f374665c51a4e5baba41e1aa6017cd725 100644 (file)
--- a/src/doxygen-mainpage.h
+++ b/src/doxygen-mainpage.h
@@ -5,8 +5,9 @@ This document contains programmer documentation of some parts of
 software developed by Eurobot team at Department of Control
 Engineering, FEE, Czech Technical University. .
 
-Currently, there is documentation to these parts:
+Currently, these modules are documented:
 - \subpage compilation
+- \subpage logging
 - \ref fsm
 - \ref trgen
 - \ref maplib
@@ -111,4 +112,43 @@ export CONFIG_OPEN_LOOP=y
 make -e  # the -e option is important!
 \endverbatim
 
+\page logging Logging
+
+We use uLUt library for logging. printf() should never be used for
+printing some information - error message, debug data etc. Instead
+ul_logXXX(), which is declared in ul_log.h, should be used.
+
+\section loghowto Howto
+
+In every file, where you want to log something you must initialize
+ul_log.h library by using UL_LOG_CUST macro and defining the name of
+the log domain:
+\code
+UL_LOG_CUST(ulogd_robot); // Log domain name = "ulogd_" + the name of the source file
+\endcode
+
+Then, you can use one of the functions (macros) bellow. Each macro
+logs a message with different severity. The severity should be chosen
+according to the following rules:
+
+- ul_logfatal() - fatal error which causes the program to terminate.
+  These error should only be reported at program startup, not while
+  the program is running for a while.
+
+- ul_logerr() - error i.e. something that should not happen during
+  normal operation. The application should be able to continue,
+  possibly with its functionality limited.
+
+- ul_logmsg() - important information that should always be seen by
+  the operator. These messages with this log level are printed by
+  default.
+
+- ul_loginf() - not so important information, which is normally
+  suppressed and is displayed only on request.
+
+- ul_logdeb() - debuging information. This information is only useful
+  to someone who knows the details of the source code.
+
+- ul_logtrash() - lowlevel debugging information.
+
 */