From 789a803b7c9c6d271d30d1278f734fb26b557ed9 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Tue, 6 Jun 2017 14:40:20 -0600 Subject: [PATCH] Better link to the exception module. --- examples/step-5/step-5.cc | 6 ++++-- examples/step-6/step-6.cc | 5 +++-- include/deal.II/base/exceptions.h | 31 ++++++++++++++++++++++--------- 3 files changed, 29 insertions(+), 13 deletions(-) diff --git a/examples/step-5/step-5.cc b/examples/step-5/step-5.cc index b67f1f2b3d..dcb9c3a513 100644 --- a/examples/step-5/step-5.cc +++ b/examples/step-5/step-5.cc @@ -416,11 +416,13 @@ void Step5::run () // the condition which is given as first argument is valid, and if not // throws an exception (its second argument) which will usually terminate // the program giving information where the error occurred and what the - // reason was. This generally reduces the time to find programming errors + // reason was. (A longer discussion of what exactly the @p Assert macro + // does can be found in the @ref Exceptions "exception documentation module".) + // This generally reduces the time to find programming errors // dramatically and we have found assertions an invaluable means to program // fast. // - // On the other hand, all these checks (there are over 9000 of them in the + // On the other hand, all these checks (there are over 10,000 of them in the // library at present) should not slow down the program too much if you want // to do large computations. To this end, the Assert macro is // only used in debug mode and expands to nothing if in optimized diff --git a/examples/step-6/step-6.cc b/examples/step-6/step-6.cc index 30822f39d5..db0e868c7b 100644 --- a/examples/step-6/step-6.cc +++ b/examples/step-6/step-6.cc @@ -579,9 +579,10 @@ void Step6::refine_grid () // hack with an explicit assertion at the beginning of the function. If this // assertion is triggered, i.e. when cycle is larger than or // equal to 10, an exception of type ExcNotImplemented is raised, -// indicating that some functionality is not implemented for this case (the +// indicating that some functionality is not implemented for this case -- the // functionality that is missing, of course, is the generation of file names -// for that case): +// for that case. (A longer discussion of what exactly the @p Assert macro +// does can be found in the @ref Exceptions "exception documentation module".) template void Step6::output_results (const unsigned int cycle) const { diff --git a/include/deal.II/base/exceptions.h b/include/deal.II/base/exceptions.h index 4ed28c650b..37a771bf0c 100644 --- a/include/deal.II/base/exceptions.h +++ b/include/deal.II/base/exceptions.h @@ -185,6 +185,8 @@ namespace deal_II_exceptions * * Previously set additional output is replaced by the argument given to * this function. + * + * @see Exceptions */ void set_additional_assert_output (const char *const p); @@ -195,6 +197,8 @@ namespace deal_II_exceptions * to compare the output of a program across different machines and systems, * since the stacktrace shows memory addresses and library names/paths that * depend on the exact setup of a machine. + * + * @see Exceptions */ void suppress_stacktrace_in_exceptions (); @@ -208,6 +212,8 @@ namespace deal_II_exceptions * for example in regression tests. Please note that some fatal errors will * still call abort(), e.g. when an exception is caught during exception * handling. + * + * @see Exceptions */ void disable_abort_on_exception (); @@ -305,11 +311,13 @@ namespace deal_II_exceptions /** - * This is the main routine in the exception mechanism for debug mode error - * checking. It asserts that a certain condition is fulfilled, otherwise + * A macro that serves as the main routine in the exception mechanism for debug mode + * error checking. It asserts that a certain condition is fulfilled, otherwise * issues an error and aborts the program. * - * See the ExceptionBase class for more information. + * A more detailed description can be found in the @ref Exceptions documentation + * module. It is first used in step-5 and step-6. + * See also the ExceptionBase class for more information. * * @note Active in DEBUG mode only * @ingroup Exceptions @@ -332,13 +340,14 @@ namespace deal_II_exceptions /** * A variant of the Assert macro above that exhibits the same runtime - * behaviour as long as disable_abort_on_exception was not called. + * behavior as long as disable_abort_on_exception was not called. * * However, if disable_abort_on_exception was called, this macro merely prints * the exception that would be thrown to deallog and continues normally * without throwing an exception. * - * See the ExceptionBase class for more information. + * A more detailed description can be found in the @ref Exceptions documentation + * module, in the discussion about the corner case at the bottom of the page. * * @note Active in DEBUG mode only * @ingroup Exceptions @@ -361,11 +370,15 @@ namespace deal_II_exceptions /** - * This is the main routine in the exception mechanism for run-time mode error - * checking. It assert that a certain condition is fulfilled, otherwise issues - * an error and aborts the program. + * A macro that serves as the main routine in the exception mechanism for dynamic + * error checking. It asserts that a certain condition is fulfilled, otherwise + * throws an exception via the C++ @p throw mechanism. This exception can + * be caught via a @p catch clause, as is shown in step-6 and all following + * tutorial programs. * - * See the ExceptionBase class for more information. + * A more detailed description can be found in the @ref Exceptions documentation + * module. It is first used in step-9 and step-13. + * See also the ExceptionBase class for more information. * * @note Active in both DEBUG and RELEASE modes * @ingroup Exceptions -- 2.39.5