]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Update text a bit.
authorWolfgang Bangerth <bangerth@math.tamu.edu>
Tue, 21 Feb 2006 05:14:51 +0000 (05:14 +0000)
committerWolfgang Bangerth <bangerth@math.tamu.edu>
Tue, 21 Feb 2006 05:14:51 +0000 (05:14 +0000)
git-svn-id: https://svn.dealii.org/trunk@12432 0785d39b-7218-0410-832d-ea1e28bc413d

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

index 6dcf4e76470cfc57d909542a3c78941ca9cc78ac..f98b3ad3dc0a923252d8e1e8f23c84dd87f5066d 100644 (file)
@@ -64,7 +64,7 @@
  *
  *  The error handling mechanism in <tt>deal.II</tt> 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
+ *  which are not fully tested. When the program shows no errors anymore, one may
  *  switch off error handling and get better performance by this, since checks
  *  for errors are done quite frequently in the library (a typical speed up is
  *  a factor of four!). This mode of exception generation is most useful for
  *  this.
  *
  *  Both modes use exception classes, which need to have special features
- *  in additional to the <tt>C++</tt> standard's <tt>exception</tt> class. Such a class
- *  is declared by the following lines of code:
+ *  in additional to the <tt>C++</tt> standard's <tt>std::exception</tt> class.
+ *  Such a class is declared by the following lines of code:
  *   @code
  *     DeclException2 (ExcDomain, int, int,
  *                     << "Index= " << arg1 << "Upper Bound= " << arg2);
  *  @endcode
+ *  
  *  This declares an exception class named <tt>ExcDomain</tt>, which
- *  has two variables as additional information (named
- *  <tt>arg1</tt> and <tt>arg2</tt> by default) and which outputs the
- *  given sequence (which is appended to an <tt>std::ostream</tt>
- *  variable's name, thus the weird syntax). There are
- *  other <tt>DeclExceptionN</tt> macros for exception classes
- *  with more or no parameters. It is proposed to let start
- *  the name of all exceptions by <tt>Exc...</tt> 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
- *  <tt>DeclExceptionN(...)</tt> macro family in both modes; there is no need to
- *  declare different classes for each of these.
- *
- *
- *  <h3>Use of the debug mode exceptions</h3>
+ *  has two variables as additional information (named <tt>arg1</tt>
+ *  and <tt>arg2</tt> by default) and which outputs the given sequence
+ *  (which is appended to an <tt>std::ostream</tt> variable's name,
+ *  thus the weird syntax). There are other <tt>DeclExceptionN</tt>
+ *  macros for exception classes with more or no parameters. By
+ *  convention, the name of all exception classes starts with
+ *  <tt>Exc...</tt> and most of them are declared locally to the class
+ *  it is to be used in (a few very frequently found ones are also
+ *  declared in the StandardExceptions namespace and are available
+ *  everywhere). Declaring exceptions globally is possible but
+ *  pollutes the global namespace, is less readable and most of the time
+ *  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 <tt>DeclExceptionN(...)</tt> macro family for both
+ *  static as well as dynamic checks.
+ *
+ *
+ *  <h3>Use of the debug mode exceptions (static checks)</h3>
  *
  *  To use the exception mechanism for debug mode error checking, write lines
  *  like the following in your source code:
  *  @code
  *    Assert (n<dim, ExcDomain(n,dim));
  *  @endcode
- *  which by macro expansion does the following:
+ *  which by macro expansion does essentially the following:
  *  @code
  *    #ifdef DEBUG
  *        if (!(cond))
  *
  *  If the <tt>DEBUG</tt> preprocessor directive is set, the call <tt>Assert
  *  (cond, exc);</tt> 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)
+ *  following sequence:
  *  @code
  *    if (!(cond))
  *      deal_II_exceptions::internals::issue_error_assert_1
  *              #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 <tt>exc</tt> is created (this is normally an
- *  unnamed object like in <tt>ExcDomain (n, dim)</tt> of class
- *  <tt>ExcDomain</tt>) and transferred to the deal_II_exceptions::internals::issue_error_assert_1()
- *  function.
+ *  
+ *  (Note that function names and exact calling sequences may change
+ *  over time, but the general principle remains the same.) 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 passed to the
+ *  deal_II_exceptions::internals::issue_error_assert_1()
+ *  function. Additionally an object of the form given by <tt>exc</tt>
+ *  is created (this is normally an unnamed object like in
+ *  <tt>ExcDomain (n, dim)</tt> of class <tt>ExcDomain</tt>) and
+ *  transferred to this function.
  *
  *  <tt>__PRETTY__FUNCTION__</tt> 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 <tt>"(not available)"</tt> otherwise.
  *
- *  In <tt>__IssueError</tt> the given data is transferred into the
- *  <tt>exc</tt> object by calling the set_fields() function; after that, the
- *  general error info is printed onto <tt>std::cerr</tt> using the
- *  PrintError() function of <tt>exc</tt> and finally the exception specific
- *  data is printed using the user defined function PrintError() (which is
- *  normally created using the <tt>DeclException (...)</tt> macro family. If
- *  it can be obtained from the operating system, the output may also contain
- *  a stacktrace to show where the error happened.
+ *  In <tt>issue_error_assert</tt>, the given data is transferred into
+ *  the <tt>exc</tt> object by calling the set_fields() function;
+ *  after that, the general error info is printed onto
+ *  <tt>std::cerr</tt> using the PrintError() function of <tt>exc</tt>
+ *  and finally the exception specific data is printed using the user
+ *  defined function PrintError() (which is normally created using the
+ *  <tt>DeclException (...)</tt> macro family. If it can be obtained
+ *  from the operating system, the output may also contain a
+ *  stacktrace to show where the error happened. Several of the
+ *  @ref Tutorial programs show a typical output.
  *
  *  After printing all this information,
  *  deal_II_exceptions::internals::abort() is called (with one
  *  @verbatim
  *    Assert (false, ExcInternalError());
  *  @endverbatim
+ *  See the @ref step_7 "step-7" and several other of the tutorial programs for
+ *  a use of this construct.
  *
  *  As mentioned above, the program is terminated once a call to
  *  <tt>Assert</tt> fails. However, there is one case where we do not want
  *
  *  <h3>Use of run-time exceptions</h3>
  *
- *  For this mode, the standard <tt>C++</tt> <tt>throw</tt> and <tt>catch</tt> concept exists. We
+ *  For this mode, the standard <tt>C++</tt> <tt>throw</tt> and <tt>catch</tt>
+ *  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
  *  @code
  *
  *  <h3>Description of the DeclExceptionN macro family</h3>
  *
- *  Declare an exception class without any additional parameters.
- *  There is a whole family of <tt>DeclException?</tt> macros
- *  where <tt>?</tt> is to be replaced by the number of additional
+ *  There is a whole family of <tt>DeclExceptionX</tt> macros
+ *  where <tt>X</tt> is to be replaced by the number of additional
  *  parameters (0 to 5 presently).
- *  
- *  The syntax is as follows:
+ *  These macros are used to declare exception classes in the following
+ *  way:
  *  @code
  *    DeclException2 (ExcDomain,
  *                    int,
  *                    int,
  *                    << " i=" << arg1 << ", m=" << arg2);
  *  @endcode
- *  The first is the name of the exception class to be created.
+ *  The first argument denotes 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
+ *  case there two types, corresponding to the <tt>X</tt> in
+ *  <tt>DeclExceptionX</tt>) and finally the output
  *  sequence with which you can print additional information.
  *  
  *  The syntax of the output sequence is a bit weird but gets
- *  clear once you see how this macro is defined:
+ *  clearer once you see how this macro is defined (again schematically, actual
+ *  function names and definitions may change over time and be different):
  *  @code
  *  class name : public ExceptionBase {
  *    public:

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.