diff --git a/Core/Documentation/Doxygen/Concepts/Logging.dox b/Core/Documentation/Doxygen/Concepts/Logging.dox index 2d3e8961a3..d5185bb0f3 100644 --- a/Core/Documentation/Doxygen/Concepts/Logging.dox +++ b/Core/Documentation/Doxygen/Concepts/Logging.dox @@ -1,25 +1,77 @@ /** \page LoggingPage Logging Concept -Logging in MITK - Available sections: --# \ref Sec1 "Section 1" --# \ref Sec2 "Section 2" +-# \ref Sec1 "Basic Information on Logging" +-# \ref Sec2 "Categorize your Logging Messages" +-# \ref Sec3 "Logging Levels" +-# \ref Sec4 "Conditional Logging" + + +\section Sec1 Basic Information on Logging +To use logging in MITK you can stream your messages into a logging stream, similar to the "std::cout" stream in standard c++. A simple example is shown next. +\code +MITK_INFO << "Here comes my message"; +\endcode +Please only use the MITK_INFO (respectively MITK_WARN, MITK_ERROR, MITK_FATAL, MITK_DEBUG, see section "Logging levels" for more details) in MITK, the std::cout stream should not be used. +You can also log object information, like shown in the next example. +\code +MITK_INFO << "I want to log my vector size: " << m_vector.getSize(); +\endcode +All logged information will be displayed in the console and be written to a logging file in the MITK folder. Advanced users may want to know that this behavior is controlled by the logging backend class, which can be adapted if you want to change the behavior. +This is everything you need to know about simple logging. Further reading will show you how you can categorize your logging message and what logging levels are. + +\section Sec2 Categorize your Logging Messages +You may also want to categorize your logging messages, so you can assign the message to your specific topic. You can simply add classes and subclasses to your MITK logging messages by using brackets, like shown in the next example. +\code +MITK_INFO << "no class"; +MITK_INFO("MyClass") << "single class"; +MITK_INFO("MyClass")("MySubClass") << "class with subclass"; +\endcode +This classes makes it easy to e.g. simply filter your logging messages only for relevant information. -\section Sec1 Section 1 +\section Sec3 Logging Levels +MITK offers different logging levels. You may mostly want to use MITK_INFO, but please consider using the other levels when logging e.g. debug information or errors. -TODO +Debug (MITK_DEBUG): These messages are designed for debug output, used to debug your source code. They are only displayed, if you turn the CMake-Variable MBILOG_ENABLE_DEBUG_MESSAGES on. You can also use the debug message in release mode, output only depends on the CMake-Variable. -\section Sec2 Section 2 +Example: +\code +MITK_DEBUG << "Result of method LoadPicture(): true." +\endcode -TODO +Info (MITK_INFO): For standard information messages that inform about expected changes/results in the program flow. Info messages should be important and understandable for the users of the program. +Example: \code -set(MODULE_CUSTOM_TESTS - ... - mitkImageVtkMapper2D.cpp -) +MITK_INFO << "The picture test.pic has been loaded successfully." \endcode + +Warning (MITK_WARN): Warning messages should inform about unexpected or potentially problematic states in the program flow that do not lead directly to an error. Thus, after a warning the program should be able continue without errors and in a clear state. + +Example: +\code +MITK_WARN << "The picture test.pic was not loaded because access was denied." +\endcode + +Error (MITK_ERROR): Error messages notify the user about corrupt states in the program flow. Such states may occur after unexpected behavior of source code. +Example: +\code +MITK_ERROR << "Error while adding test.pic to the data storage, aborting." +\endcode + +Fatal (MITK_FATAL): Fatal messages report corrupt states in the program flow that lead directly to a crash of the program. + +Example: +\code +MITK_FATAL << "Memory allocation error during instantiation of image object." +\endcode + +\section Sec4 Conditional Logging +Another feature of the logging mechanism is that you can directly give conditions if your message should be logged. This bool values or expressions can be defined in brackets. An example is shown next. +\code +MITK_INFO(x>1000) << "x is too large"; //logs only if x > 1000 +\endcode + */ \ No newline at end of file