diff --git a/Core/Documentation/Doxygen/Concepts/Exceptions.dox b/Core/Documentation/Doxygen/Concepts/Exceptions.dox index f8d2298d27..09637a71b2 100644 --- a/Core/Documentation/Doxygen/Concepts/Exceptions.dox +++ b/Core/Documentation/Doxygen/Concepts/Exceptions.dox @@ -1,46 +1,88 @@ -namespace mitk{ /** \page ExceptionPage Error Handling and Exception Concept -\ref ExceptionHandling "General Exception Handling" -\ref SpecializedExceptionHandling "Defining and Using more Specialized Exceptions" +\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. Exceptions should always be thrown by using the pre defined exception macros. If you want to throw a mitk::exception in your code, simply use the following macro. +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. + +\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. \code -//This command will throw a mitk::exception and add the message. +//This command will throw a mitk::Exception and add the message. //The macro will also add filename and line number to the exception //object. mitkThrow() << "Here comes your exception message"; \endcode You can also stream more complex messages, e.g. adding integers or other variables to your exception messages, like shown in the following example. \code mitkThrow() << "This time we show the values of some variables:" << m_MyObject->GetSize() << m_MyInteger; \endcode -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 \li LoggingPage for more details on error logging. +\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. + +\code +/** 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."; + } +\endcode + +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. -\ref SpecializedExceptionHandling Defining and Using more Specialized Exceptions +\subsection Catch Catching exceptions -The basic MITK exception concept was kept very simple and should suffice in many cases. But if you need more specialized exceptions, this is also possible. 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. +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. + +\code +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. + } +\endcode + +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. \code #include #include class mitk::MySpecializedException : public mitk::Exception { public: mitkExceptionClassMacro(mitk::MySpecializedException,mitk::Exception); }; \endcode To throw your specialized exception you should use the corresponing macro, which is shown in the next code snippet. \code mitkThrowException(mitk::MySpecializedException) << "this is error info"; -\endcode \ No newline at end of file +\endcode +*/ \ No newline at end of file