diff --git a/Core/Documentation/Doxygen/Concepts/Exceptions.dox b/Core/Documentation/Doxygen/Concepts/Exceptions.dox index 189b017463..e3f3149380 100644 --- a/Core/Documentation/Doxygen/Concepts/Exceptions.dox +++ b/Core/Documentation/Doxygen/Concepts/Exceptions.dox @@ -1,93 +1,92 @@ /** \page ExceptionPage Error Handling and Exception Concept \ref ExceptionHandling "1. General Exception Handling" \ref SpecializedExceptionHandling "2. Defining and Using Specialized Exceptions" \section ExceptionHandling General Exception Handling -In MITK, errors during program execution are handled by the well known exception handling concept which is part of the C++ language. In case of unexpected exceptional behaviour or errors during program execution MITK classes throw exceptions. MITK exceptions are always objects of the class mitk::Exception or its subclasses. +In MITK, errors during program execution are handled by the well known exception handling concept which is part of the C++ language. In case of unexpected exceptional behaviour or errors during program execution MITK classes throw exceptions. MITK exceptions are always objects of the class mitk::Exception or of one of its subclasses. \subsection Throw Throwing of exceptions Exceptions should always be thrown by using the predefined exception macros. If you want to throw a mitk::Exception in your code, simply use the following macro. \verbatim -//This command will throw a mitk::Exception and add the message. +//This command will throw a mitk::Exception and add a message. //The macro will also add filename and line number to the exception //object. mitkThrow() << "Here comes your exception message"; \endverbatim You can also stream more complex messages, e.g. adding integers or other variables to your exception messages, like shown in the following example. \verbatim mitkThrow() << "This time we show the values of some variables:" << m_MyObject->GetSize() << m_MyInteger; \endverbatim \subsection Doc Documentation of exceptions -If you throw exceptions in your code please also document this in your doxygen comments by using the "@throws " tag. This will help users of your class to catch and handle the exceptions in a proper way. An example how to document exception throwing is given below. +If you throw exceptions in your code, please also document this in your doxygen comments by using the "@throws " tag. This will help users of your class to catch and handle the exceptions in a proper way. An example how to document exception throwing is given below. \verbatim class myExampleClass { /** Documentation * @brief This method does [...] * @throws mitk::Exception This exception is thrown, when the following error occures: [...] */ void MyExampleMethod() { //here comes your code //here happens an exception mitkThrow() << "An exception occured because [...], method can't continue."; } } \endverbatim -In general exception emit no logging messages by default because they are intended to be catched by overlying classes. This classes should then decide what to do, e.g. to log an error message or handle the exception in another way. See the logging documentation for more details on error logging. +In general, exceptions emit no logging messages by default because they are intended to be catched by overlying classes. This classes should then decide what to do, e.g. to log an error message or handle the exception in another way. See the logging documentation for more details on error logging. \subsection Catch Catching exceptions -Exceptions should be catched in overlying classes, when they can be handled in a proper way. Catching exceptions is very simple, use the standard try-catch block to do so. An example is given below. +Exceptions should be catched by overlying classes, when they can handle them in a proper way. Catching exceptions is very simple, use the standard try-catch block to do so. An example is given below. \verbatim try { //call of a method which may throw an exception myObject->MyExampleMethod(); } catch (mitk::Exception e) { //This code is executed if an exception of the given type was thrown above. //For example log an error message here or do some other proper handling of the exception. } \endverbatim Please do not use "catch (...)" because normally your class can't garantee to handle all exceptions in a proper way without differentiate them. \section SpecializedExceptionHandling Defining and Using more Specialized Exceptions -The basic MITK exception concept was kept very simple and should suffice in many cases. But you can also use more specialized exceptions, if needed. Nevertheless all MITK exceptions should be subclasses of mitk::exception. You can define your own exception classes by simply implementing new classes which derive from mitk::exception. Thus, you can catch your exception seperately when needed. By using the mitkExceptionClassMacro implementing new exception classes is simple, like shown in the following code example. +The basic MITK exception concept was kept very simple and should suffice in many cases. But you can also use more specialized exceptions, if needed. Nevertheless all MITK exceptions should be subclasses of mitk::exception. You can define your own exception classes by simply implementing new classes which derive from mitk::exception. Thus, you can catch your exception seperately when needed. The mitkExceptionClassMacro helps to keep implementing new exception classes as simple as possible, like shown in the following code example. \verbatim -#include #include class mitk::MySpecializedException : public mitk::Exception { public: mitkExceptionClassMacro(mitk::MySpecializedException,mitk::Exception); }; \endverbatim To throw your specialized exception you should use the corresponing macro, which is shown in the next code snippet. \verbatim mitkThrowException(mitk::MySpecializedException) << "this is error info"; \endverbatim */ \ No newline at end of file diff --git a/Core/Documentation/Doxygen/Concepts/Logging.dox b/Core/Documentation/Doxygen/Concepts/Logging.dox index d5185bb0f3..de6aef863d 100644 --- a/Core/Documentation/Doxygen/Concepts/Logging.dox +++ b/Core/Documentation/Doxygen/Concepts/Logging.dox @@ -1,77 +1,78 @@ /** \page LoggingPage Logging Concept Available sections: -# \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. +All logged information will be displayed in the console and be written to a logging file in the MITK binary 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. +You may also want to categorize your logging messages, so you can assign messages 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. +This classes makes it easy to e.g. simply filter all logging messages only for relevant information. \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. +MITK offers different logging levels. You may mostly want to use MITK_INFO, but please consider using the other levels, e.g. when logging debug information or errors. -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. +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. Example: \code MITK_DEBUG << "Result of method LoadPicture(): true." \endcode 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 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. +Another feature of the logging mechanism is that you can directly give conditions if your message should be logged. These 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