// $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
/**
* In this namespace functions in connection with the Assert and
* AssertThrow mechanism are declared.
+ *
+ * @ingroup Exceptions
*/
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
{
*
* See the ExceptionBase class for more information.
*
+ * @ingroup Exceptions
* @author Wolfgang Bangerth, November 1997, extensions 1998
*/
#define Assert(cond, exc) \
* See the <tt>ExceptionBase</tt> class for more information.
*
* @ref ExceptionBase
+ * @ingroup Exceptions
* @author Wolfgang Bangerth, November 1997, extensions 1998
*/
#ifndef DISABLE_ASSERT_THROW
/**
* Declare an exception class derived from ExceptionBase without parameters.
* @author Wolfgang Bangerth, November 1997
+ * @ingroup Exceptions
*/
#define DeclException0(Exception0) \
class Exception0 : 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 { \
/**
* Declare an exception class derived from ExceptionBase with
* three additional parameters.
+ * @ingroup Exceptions
*/
#define DeclException3(Exception3, type1, type2, type3, outsequence) \
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 { \
/**
* 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 { \
* @code
* using namespace StandardExceptions;
* @endcode
+ *
+ * @ingroup Exceptions
*/
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
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
//-------------------------------------------------------------------------
/**
- * @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
*/