]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Better document the exception mechanism.
authorWolfgang Bangerth <bangerth@math.tamu.edu>
Sat, 14 Jan 2006 00:53:05 +0000 (00:53 +0000)
committerWolfgang Bangerth <bangerth@math.tamu.edu>
Sat, 14 Jan 2006 00:53:05 +0000 (00:53 +0000)
git-svn-id: https://svn.dealii.org/trunk@12022 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/base/include/base/exceptions.h
deal.II/doc/doxygen/headers/exceptions.h

index d209c9d065e87d2aeca4b13b51b44ad2d962f2f7..f007e71a7766697a3274d25991da49ba3faa8384 100644 (file)
@@ -2,7 +2,7 @@
 //    $Id$
 //    Version: $Name$
 //
-//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 by the deal.II authors
+//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 by the deal.II authors
 //
 //    This file is subject to QPL and may not be  distributed
 //    without copyright and license information. Please refer
  *  also no output sequence is allowed.
  *
  *
+ *  @ingroup Exceptions
  *  @author Wolfgang Bangerth, November 1997, extensions 1998
  */
 class ExceptionBase : public std::exception
@@ -453,6 +454,8 @@ class ExceptionBase : public std::exception
 /**
  * In this namespace functions in connection with the Assert and
  * AssertThrow mechanism are declared.
+ * 
+ * @ingroup Exceptions
  */
 namespace deal_II_exceptions
 {
@@ -533,6 +536,8 @@ namespace deal_II_exceptions
  * and AssertThrow mechanism but are solely for internal purposes and
  * are not for use outside the exception handling and throwing
  * mechanism.
+ * 
+ *  @ingroup Exceptions
  */
   namespace internals
   {
@@ -621,6 +626,7 @@ namespace deal_II_exceptions
  *
  * See the ExceptionBase class for more information.
  *
+ * @ingroup Exceptions
  * @author Wolfgang Bangerth, November 1997, extensions 1998
  */
 #define Assert(cond, exc)                                           \
@@ -659,6 +665,7 @@ namespace deal_II_exceptions
  * See the <tt>ExceptionBase</tt> class for more information.
  *
  * @ref ExceptionBase
+ * @ingroup Exceptions
  * @author Wolfgang Bangerth, November 1997, extensions 1998
  */
 #ifndef DISABLE_ASSERT_THROW
@@ -695,6 +702,7 @@ namespace deal_II_exceptions
 /**
  * Declare an exception class derived from ExceptionBase without parameters.
  * @author Wolfgang Bangerth, November 1997
+ * @ingroup Exceptions
  */
 #define DeclException0(Exception0)  \
 class Exception0 :  public ExceptionBase {}
@@ -722,6 +730,7 @@ class Exception1 : public ExceptionBase {                             \
 /**
  *  Declare an exception class derived from ExceptionBase with
  *  two additional parameters.
+ *  @ingroup Exceptions
  */
 #define DeclException2(Exception2, type1, type2, outsequence)         \
 class Exception2 : public ExceptionBase {                             \
@@ -742,6 +751,7 @@ class Exception2 : public ExceptionBase {                             \
 /**
  *  Declare an exception class derived from ExceptionBase with
  *  three additional parameters.
+ *  @ingroup Exceptions
  */
 #define DeclException3(Exception3, type1, type2, type3, outsequence)  \
 class Exception3 : public ExceptionBase {                             \
@@ -763,6 +773,7 @@ class Exception3 : public ExceptionBase {                             \
 /**
  *  Declare an exception class derived from ExceptionBase with
  *  four additional parameters.
+ *  @ingroup Exceptions
  */
 #define DeclException4(Exception4, type1, type2, type3, type4, outsequence) \
 class Exception4 : public ExceptionBase {                             \
@@ -786,6 +797,7 @@ class Exception4 : public ExceptionBase {                             \
 /**
  *  Declare an exception class derived from ExceptionBase with
  *  five additional parameters.
+ *  @ingroup Exceptions
  */
 #define DeclException5(Exception5, type1, type2, type3, type4, type5, outsequence) \
 class Exception5 : public ExceptionBase {                             \
@@ -815,6 +827,8 @@ class Exception5 : public ExceptionBase {                             \
  * @code
  * using namespace StandardExceptions;
  * @endcode
+ *
+ * @ingroup Exceptions
  */
 namespace StandardExceptions 
 {
@@ -953,11 +967,11 @@ namespace StandardExceptions
                                    */
   DeclException0 (ExcNotInitialized);
 
-                                    /**
-                                     * The object is in a state not
-                                     * suitable for this operation.
-                                     */
-    DeclException0 (ExcInvalidState);
+                                   /**
+                                    * The object is in a state not
+                                    * suitable for this operation.
+                                    */
+  DeclException0 (ExcInvalidState);
     
                                   /**
                                    * This exception is raised if a
@@ -1000,14 +1014,14 @@ namespace StandardExceptions
                  int, int,
                  << "Dimension " << arg1 << " not equal to " << arg2);
 
-                                    /**
-                                     * The first dimension should be
-                                     * either equal to the second or
-                                     * the third, but it is neither.
-                                     */
-    DeclException3 (ExcDimensionMismatch2,
-                   int, int, int,
-                   << "Dimension " << arg1 << " neither equal to " << arg2 << " nor to " << arg3);
+                                   /**
+                                    * The first dimension should be
+                                    * either equal to the second or
+                                    * the third, but it is neither.
+                                    */
+  DeclException3 (ExcDimensionMismatch2,
+                  int, int, int,
+                  << "Dimension " << arg1 << " neither equal to " << arg2 << " nor to " << arg3);
 
                                   /**
                                    * This exception is one of the
index 27b10548edbe73a64e189f606c882de3bf307aff..48d148a2a812f7824085e2b6a2e04b174f2d57f0 100644 (file)
 //-------------------------------------------------------------------------
 
 /**
- * @defgroup Exceptions Exceptions
+ * @defgroup Exceptions Exceptions and assertions
  *
+ * This module contains classes that are used in the exception mechanism of
+ * deal.II. Exceptions are used in two different ways:
+ *
+ * <ul>
+ * 
+ *   <li> Static assertions: These are checks that are only enabled in debug
+ *   mode, not in optimized (or production) mode. They are meant to check that
+ *   parameters to functions satisfy certain properties and similar
+ *   assertions. For example, static assertions are used to make sure that two
+ *   vectors that are added together have the same number of components --
+ *   everything else would not make any sense anyway.
+ *
+ *   Such checks are performed by the Assert macro in several thousand places
+ *   within the library. Also, several tutorial programs starting with step-5
+ *   show how to do this.
+ *
+ *   If a static assertion is violated, the exception mechanism generates an
+ *   exception of a type that indicates what exactly goes wrong, displays
+ *   appropriate information, and then aborts the program -- if you try to add
+ *   two vectors of different length, there is nothing that can be done within
+ *   the program to cope with the situation, you have to go fix the program
+ *   code instead. The exceptions of this module are used to indicate the
+ *   reason for the failure.
+ *
+ *
+ *   <li> Dynamic assertions: These are used to check dynamic features, such
+ *   as whether an output file can be written to. These are things that can't
+ *   be checked statically, i.e. they may change from program run to program
+ *   run. It is therefore insufficient to only check these situations in debug
+ *   mode.
+ *
+ *   Rather, one has to check them every time during execution of a
+ *   program. Within deal.II, this is done using the AssertThrow macro
+ *   introduced in step-9, step-13, and following tutorial programs. The macro
+ *   checks a condition, and if violated throws an exception of one of the
+ *   types declared in this module, using the C++ <code>throw</code>
+ *   mechanism. Since these are run-time exceptions, this gives the program
+ *   the chance to catch the exception and, for example, write the output to a
+ *   writable file instead.
+ * </ul>
+ *   
  * @author Wolfgang Bangerth, 1998-2006
  */

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.