From: Guido Kanschat Date: Fri, 9 Jan 2004 12:01:02 +0000 (+0000) Subject: Doc for doxygen X-Git-Tag: v8.0.0~15938 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=11435bd4f78a6d01bf5bcf3e3078329f055566bf;p=dealii.git Doc for doxygen git-svn-id: https://svn.dealii.org/trunk@8291 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/base/include/base/exceptions.h b/deal.II/base/include/base/exceptions.h index 3cc0c21b4b..7007c41a10 100644 --- a/deal.II/base/include/base/exceptions.h +++ b/deal.II/base/include/base/exceptions.h @@ -2,7 +2,7 @@ // $Id$ // Version: $Name$ // -// Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003 by the deal.II authors +// Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004 by the deal.II authors // // This file is subject to QPL and may not be distributed // without copyright and license information. Please refer @@ -33,12 +33,12 @@ * and variables directly since the interface * and mechanism may be subject to change. Rather * create new exception classes using the - * @p{DeclException} macro family. + * DeclException macro family. * * - * @sect2{General overview of the exception handling mechanism in deal.II} + * @section ExceptionBase General General overview of the exception handling mechanism in deal.II * - * The error handling mechanism in @p{deal.II} is generally used in two ways. + * The error handling mechanism in deal.II is generally used in two ways. * The first uses error checking in debug mode only and is useful for programs * which are not fully tested. When the program shows no error anymore, one may * switch off error handling and get better performance by this, since checks @@ -53,7 +53,7 @@ * I/O errors, failing memory requests and the like. It does not make much * sense to turn this mode off, since this kind of errors may happen in tested * and untested programs likewise. Exceptions of this kind do not terminate the - * program, rather they throw exceptions in the @p{C++} manner, allowing the + * program, rather they throw exceptions in the C++ manner, allowing the * program to catch them and eventually do something about it. As it may be * useful to have some information printed out if an exception could not be * handled properly, additional information is passed along as for the first @@ -64,122 +64,124 @@ * this. * * Both modes use exception classes, which need to have special features - * additionally to the @p{C++} standard's @p{exception} class. Such a class + * additionally to the C++ standard's exception class. Such a class * is declared by the following lines of code: - * @begin{verbatim} + * @code * DeclException2 (ExcDomain, int, int, * << "Index= " << arg1 << "Upper Bound= " << arg2); - * @end{verbatim} - * This declares an exception class named @p{ExcDomain}, which + * @endcode + * This declares an exception class named ExcDomain, which * has two variables as additional information (named - * @p{arg1} and @p{arg2} by default) and which outputs the - * given sequence (which is appended to an @p{std::ostream} + * arg1 and arg2 by default) and which outputs the + * given sequence (which is appended to an std::ostream * variable's name, thus the weird syntax). There are - * other @p{DeclExceptionN} macros for exception classes + * other DeclExceptionN macros for exception classes * with more or no parameters. It is proposed to let start - * the name of all exceptions by @p{Exc...} and to declare them locally to + * the name of all exceptions by Exc... and to declare them locally to * the class it is to be used in. Declaring exceptions globally is possible * but pollutes the global namespace, is less readable and thus unnecessary. * * Since exception classes are declared the same way for both modes of error * checking, it is possible to use an exception declared through the - * @p{DeclExceptionN(...)} macro family in both modes; there is no need to + * DeclExceptionN(...) macro family in both modes; there is no need to * declare different classes for each of these. * * - * @sect2{Use of the debug mode exceptions} + * @section ExceptionBaseUse Use of the debug mode exceptions * * To use the exception mechanism for debug mode error checking, write lines * like the following in your source code: - * @begin{verbatim} + * @code * Assert (nDEBUG is set and if the given condition (in this case + * n < dim is violated). * - * If the exception was declared using the @p{DeclException0 (...)} + * If the exception was declared using the DeclException0 (...) * macro, i.e. without any additional parameters, its name has * nonetheless to be given with parentheses: - * @p{Assert (i>m, ExcSomewhat());} + * Assert (i>m, ExcSomewhat()); * - * @sect3{How it works internally} - * If the @p{DEBUG} preprocessor directive is set, the call @p{Assert - * (cond, exc);} is basically converted by the preprocessor into the + * @subsection ExceptionBaseInternal How it works internally + * If the DEBUG preprocessor directive is set, the call Assert + * (cond, exc); is basically converted by the preprocessor into the * sequence (note that function names and exact calling sequences may * change over time, but the general principle remains the same) - * @begin{verbatim} + * @code * if (!(cond)) - * __IssueError_Assert (__FILE__, - * __LINE__, - * __PRETTY_FUNCTION__, - * #cond, - * #exc, - * &exc); - * @end{verbatim} + * deal_II_exceptions::internals::issue_error_assert_1 + * (__FILE__, + * __LINE__, + * __PRETTY_FUNCTION__, + * #cond, + * #exc, + * &exc); + * @endcode * i.e. if the given condition is violated, then the file and * line in which the exception occured as well as * the condition itself and the call sequence of the * exception object is transferred. Additionally an object - * of the form given by @p{exc} is created (this is normally an - * unnamed object like in @p{ExcDomain (n, dim)} of class - * @p{ExcDomain}) and transferred to the @p{__IssueError_Assert} + * of the form given by exc is created (this is normally an + * unnamed object like in ExcDomain (n, dim) of class + * ExcDomain) and transferred to the deal_II_exceptions::internals::issue_error_assert_1() * function. * - * @p{__PRETTY__FUNCTION__} is a macro defined by some compilers and + * __PRETTY__FUNCTION__ is a macro defined by some compilers and * gives the name of the function. If another compiler is used, we * try to set this function to something reasonable, if the compiler - * provides us with that, and @p{"(not available)"} otherwise. - * - * In @p{__IssueError} the given data - * is transferred into the @p{exc} object by calling the - * @p{SetFields} function; after that, the general error info - * is printed onto @p{std::cerr} using the @p{PrintError} function of - * @p{exc} and finally the exception specific data is printed - * using the user defined function @p{PrintError} (which is - * normally created using the @p{DeclException (...)} macro + * provides us with that, and "(not available)" otherwise. + * + * In __IssueError the given data + * is transferred into the exc object by calling the + * SetFields() function; after that, the general error info + * is printed onto std::cerr using the PrintError() function of + * exc and finally the exception specific data is printed + * using the user defined function PrintError() (which is + * normally created using the DeclException (...) macro * family. * - * After printing all this information, @p{abort()} is called (with - * one exception, see the end of this section). This terminates the + * After printing all this information, + * deal_II_exceptions::internals::abort() is called (with one + * exception, see the end of this section). This terminates the * program, which is the right thing to do for this kind of error * checking since it is used to detect programming errors rather than * run-time errors; a program can, by definition, not recover from * programming errors. * - * If the preprocessor variable @p{DEBUG} is not set, then nothing - * happens, i.e. the @p{Assert} macro is expanded to @p{{}}. + * If the preprocessor variable DEBUG is not set, then nothing + * happens, i.e. the Assert macro is expanded to {}. * * Sometimes, there is no useful condition for an exception other * than that the program flow should not have reached a certain point, - * e.g. a @p{default} section of a @p{switch} statement. In this case, + * e.g. a default section of a switch statement. In this case, * raise the exception by the following construct: * @begin{verbatim} * Assert (false, ExcInternalError()); * @end{verbatim} * * As mentioned above, the program is terminated once a call to - * @p{Assert} fails. However, there is one case where we do not want + * Assert fails. However, there is one case where we do not want * to do this, namely when a C++ exception is active. The usual case * where this happens is that someone throws an exception through the - * @p{AssertThrow} mechanism (see below) which, while the stack is + * AssertThrow mechanism (see below) which, while the stack is * unwound, leads to the destruction of other objects in stack frames * above. If other objects refer to the objects being thus destroyed, - * some destructors raise an exception through @p{Assert}. If we + * some destructors raise an exception through Assert. If we * would abort the program then, we would only ever see the message * that an object is being destroyed which is still referenced from * somewhere, but we would never see the original exception that * triggered this. (You can see it in the debugger by putting a break - * point on the function @p{__throw}, but you cannot see it from the + * point on the function __throw, but you cannot see it from the * program itself.) In that case, we use a C++ standard library * function to detect the presence of another active exception and do * not terminate the program to allow that the thrown exception @@ -192,17 +194,17 @@ * message about suppressed follow-up messages is shown. * * - * @sect2{Use of run-time exceptions} + * @section ExceptionBaseUse Use of run-time exceptions * - * For this mode, the standard @p{C++} @p{throw} and @p{catch} concept exists. We + * For this mode, the standard C++ throw and catch concept exists. We * want to keep to this, but want to extend it a bit. In general, the * structure is the same, i.e. you normally raise and exception by - * @begin{verbatim} + * @code * if (!(cond)) * throw ExcSomething(); - * @end{verbatim} + * @endcode * and catch it using the statement - * @begin{verbatim} + * @code * try { * do_something (); * } @@ -212,21 +214,21 @@ * << std::endl; * do_something_to_reciver (); * }; - * @end{verbatim} - * @p{exception} is a standard @p{C++} class providing basic functionality for - * exceptions, such as the virtual function @p{what()} which returns some + * @endcode + * exception is a standard C++ class providing basic functionality for + * exceptions, such as the virtual function what() which returns some * information on the exception itself. This information is useful if an * exception can't be handled properly, in which case as precise a description * as possible should be printed. * * The problem here is that to get significant and useful information out - * of @p{what()}, it is necessary to overload this function in out exception - * class and call the @p{throw} operator with additional arguments to the - * exception class. The first thing, overloading the @p{what} function is - * done using the @p{DeclExceptionN} macros, but putting the right information, - * which is the same as explained above for the @p{Assert} expansion, requires + * of what(), it is necessary to overload this function in out exception + * class and call the throw operator with additional arguments to the + * exception class. The first thing, overloading the what function is + * done using the DeclExceptionN macros, but putting the right information, + * which is the same as explained above for the Assert expansion, requires * some work if one would want to write it down each time: - * @begin{verbatim} + * @code * if (!(cond)) * { * ExcSomething e(additional information); @@ -235,34 +237,34 @@ * "name of condition as a string"); * throw e; * }; - * @end{verbatim} + * @endcode * - * For this purpose, the macro @p{AssertThrow} was invented. It does mainly - * the same job as does the @p{Assert} macro, but it does not kill the + * For this purpose, the macro AssertThrow was invented. It does mainly + * the same job as does the Assert macro, but it does not kill the * program, it rather throws an exception as shown above. The mode of usage * is - * @begin{verbatim} + * @code * AssertThrow (cond, ExcSomething(additional information)); - * @end{verbatim} + * @endcode * The condition to be checked is incorporated into the macro in order to * allow passing the violated condition as a string. The expansion of the - * @p{AssertThrow} macro is not affected by the @p{DEBUG} preprocessor variable. + * AssertThrow macro is not affected by the DEBUG preprocessor variable. * * - * @sect2{Description of the DeclExceptionN macro family} + * @section ExceptionNMacros Description of the DeclExceptionN macro family * * Declare an exception class without any additional parameters. - * There is a whole family of @p{DeclException?} macros - * where @p{?} is to be replaced by the number of additional + * There is a whole family of DeclException? macros + * where ? is to be replaced by the number of additional * parameters (0 to 5 presently). * * The syntax is as follows: - * @begin{verbatim} + * @code * DeclException2 (ExcDomain, * int, * int, * << " i=" << arg1 << ", m=" << arg2); - * @end{verbatim} + * @endcode * The first is the name of the exception class to be created. * The next arguments are the types of the parameters (in this * case there are two type names needed) and finally the output @@ -270,7 +272,7 @@ * * The syntax of the output sequence is a bit weird but gets * clear once you see how this macro is defined: - * @begin{verbatim} + * @code * class name : public ExceptionBase { * public: * name (const type1 a1, const type2 a2) : @@ -282,17 +284,17 @@ * type1 arg1; * type2 arg2; * }; - * @end{verbatim} + * @endcode * * If declared as specified, you can later use this exception class * in the following manner: - * @begin{verbatim} + * @code * int i=5; * int m=3; * Assert (i of file . * The violated condition was: @@ -302,9 +304,9 @@ * Additional Information: * i=5, m=3 * -------------------------------------------------------- - * @end{verbatim} + * @endverbatim * - * Obviously for the @p{DeclException0(name)} macro, no types and + * Obviously for the DeclException0(name) macro, no types and * also no output sequence is allowed. * * @@ -322,7 +324,7 @@ class ExceptionBase : public std::exception * The constructor takes the file in which the * error happened, the line and the violated * condition as well as the name of the - * exception class as a @p{char*} as arguments. + * exception class as a char* as arguments. */ ExceptionBase (const char* f, const int l, const char *func, const char* c, const char *e); @@ -375,8 +377,8 @@ class ExceptionBase : public std::exception * * This function is mainly used when using * exceptions declared by the - * @p{DeclException*} macros with the @p{throw} - * mechanism or the @p{AssertThrow} macro. + * DeclException* macros with the throw + * mechanism or the AssertThrow macro. */ virtual const char * what () const throw (); @@ -421,7 +423,7 @@ namespace deal_II_exceptions * Set a string that is printed * upon output of the message * indicating a triggered - * @p{Assert} statement. This + * Assert statement. This * string, which is printed in * addition to the usual output may * indicate information that is @@ -463,7 +465,7 @@ namespace deal_II_exceptions /** * This routine does the main work for the * exception generation mechanism used in the - * @p{Assert} macro. + * Assert macro. * * @ref ExceptionBase */ @@ -478,7 +480,7 @@ namespace deal_II_exceptions /** * This routine does the main work for the * exception generation mechanism used in the - * @p{AssertThrow} macro. + * AssertThrow macro. * * @ref ExceptionBase */ @@ -498,10 +500,10 @@ namespace deal_II_exceptions /** - * Relay exceptions from the @p{Assert} macro to the - * @p{__IssueError_Assert} function. Used to convert the last + * Relay exceptions from the Assert macro to the + * __IssueError_Assert function. Used to convert the last * argument from arbitrary type to @ref{ExceptionBase} which is not - * possible inside the @p{Assert} macro due to syntactical + * possible inside the Assert macro due to syntactical * difficulties in connection with the way we use the macro and the * declaration of the exception classes. * @@ -542,9 +544,8 @@ namespace deal_II_exceptions * error checking. It asserts that a certain condition is fulfilled, * otherwise issues an error and aborts the program. * - * See the @p{ExceptionBase} class for more information. + * See the ExceptionBase class for more information. * - * @ref ExceptionBase * @author Wolfgang Bangerth, November 1997, extensions 1998 */ #define Assert(cond, exc) \ @@ -571,16 +572,16 @@ namespace deal_II_exceptions * fulfilled, otherwise issues an error and aborts the program. * * On some systems (we only know of DEC Alpha systems running under - * OSF1 or Linux), the compiler fails to compile the @p{AssertThrow} + * OSF1 or Linux), the compiler fails to compile the AssertThrow * macro properly, yielding an internal compiler error. We detect this - * at configure time. For these cases, the @p{AssertThrow} macro aborts + * at configure time. For these cases, the AssertThrow macro aborts * the program if the assertion is not satisfied. This, however, * happens in debug and optimized mode likewise. Note that in these * cases, the meaning of a program changes. In particular, one cannot - * catch exceptions thrown by @p{AssertThrow}, but we did not find + * catch exceptions thrown by AssertThrow, but we did not find * another way to work around this compiler bug. * - * See the @p{ExceptionBase} class for more information. + * See the ExceptionBase class for more information. * * @ref ExceptionBase * @author Wolfgang Bangerth, November 1997, extensions 1998 @@ -617,7 +618,7 @@ namespace deal_II_exceptions /** - * See the @p{ExceptionBase} class for a detailed description. + * See the ExceptionBase class for a detailed description. * * @ref ExceptionBase * @author Wolfgang Bangerth, November 1997 @@ -914,7 +915,7 @@ namespace StandardExceptions /** * This exception works around a * design flaw in the - * @p{DeclException0} macro: that + * DeclException0 macro: that * does not allow one to specify a * message that is displayed when * the exception is raised, as @@ -924,7 +925,7 @@ namespace StandardExceptions * * When throwing this exception, * you can give a message as a - * @p{char*} as argument to the + * char* as argument to the * exception that is then * displayed. */