From 57433b40f0feef1e73254ff49ff4f6b279fa7796 Mon Sep 17 00:00:00 2001 From: David Tardon Date: Fri, 25 Feb 2011 18:25:17 +0100 Subject: shortly describe diagnostic macros --- sal/inc/osl/diagnose.h | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/sal/inc/osl/diagnose.h b/sal/inc/osl/diagnose.h index b7b8e4308..6cba3f74b 100644 --- a/sal/inc/osl/diagnose.h +++ b/sal/inc/osl/diagnose.h @@ -32,6 +32,50 @@ #include +/** provides simple diagnostic support + + The functions defined in this header are not intended to be used directly, + but through defined macros. The macros can be divided into three categories: + assertions, traces and other stuff .-) Their usability depends on the value + of OSL_DEBUG_LEVEL macro: assertions are only active if OSL_DEBUG_LEVEL is 1 + or greater, traces if OSL_DEBUG_LEVEL is 2 or greater. + + Assertions (cond is bool, msg is char*): + OSL_ASSERT(cond) + If cond is false, reports an error. + + OSL_ENSURE(cond, msg) + If cond is false, reports an error with message msg. + + OSL_FAIL(msg) + Reports an error with message msg unconditionally. + + OSL_PRECOND(cond, msg) + OSL_POSTCOND(cond, msg) + These two are functionally equivalent to OSL_ENSURE(cond, msg). They are + intended to be used for checking pre- and postconditions of functions. + + Traces: + OSL_TRACE(fmt, args...) + Prints trace message. The arguments have the same meaning as the + arguments of printf. + + Other: + OSL_VERIFY(expr) + Evaluates the expression and if it is false, reports an error. The + expression is evaluated once without regard of the value of + OSL_DEBUG_LEVEL. + + Example: + + void extractBool(Any const& rAny, bool& rBool) + { + OSL_VERIFY(rAny >>= rBool); + } + + OSL_DEBUG_ONLY(expr) + */ + #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ -- cgit v1.2.3