From 9f1ce8bfa92ee31fcb7633f3e59564bac17ff5e8 Mon Sep 17 00:00:00 2001
From: Francesco Montorsi <f18m_cpp217828@yahoo.it>
Date: Tue, 14 Oct 2008 19:40:39 +0000
Subject: [PATCH] clarify the usage of debug macros, in particular for wxFAIL
 (which doesn't need () brackets) as reported by Jim Battle

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56311 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 interface/wx/debug.h | 48 +++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 45 insertions(+), 3 deletions(-)

diff --git a/interface/wx/debug.h b/interface/wx/debug.h
index 0f5a147b6e..d0e98d385e 100644
--- a/interface/wx/debug.h
+++ b/interface/wx/debug.h
@@ -12,9 +12,13 @@
 /**
     Assert macro. An error message will be generated if the condition is @false in
     debug mode, but nothing will be done in the release build.
+
     Please note that the condition in wxASSERT() should have no side effects
     because it will not be executed in release mode at all.
 
+    This macro should be used to catch (in debug builds) logical errors done
+    by the programmer.
+
     @see wxASSERT_MSG(), wxCOMPILE_TIME_ASSERT()
 
     @header{wx/debug.h}
@@ -25,6 +29,9 @@
     This macro results in a @ref wxCOMPILE_TIME_ASSERT "compile time assertion failure"
     if the size of the given @c type is less than @c size bits.
 
+    This macro should be used to catch (in debug builds) logical errors done
+    by the programmer.
+
     You may use it like this, for example:
 
     @code
@@ -43,6 +50,9 @@
     Assert macro with message.
     An error message will be generated if the condition is @false.
 
+    This macro should be used to catch (in debug builds) logical errors done
+    by the programmer.
+
     @see wxASSERT(), wxCOMPILE_TIME_ASSERT()
 
     @header{wx/debug.h}
@@ -53,6 +63,9 @@
     Checks that the condition is @true, returns with the given return value if
     not (stops execution in debug mode). This check is done even in release mode.
 
+    This macro should be used to catch (both in debug and release builds) logical
+    errors done by the programmer.
+
     @header{wx/debug.h}
 */
 #define wxCHECK( condition, retValue )
@@ -63,6 +76,9 @@
 
     This macro may be only used in non-void functions, see also wxCHECK_RET().
 
+    This macro should be used to catch (both in debug and release builds) logical
+    errors done by the programmer.
+
     @header{wx/debug.h}
 */
 #define wxCHECK_MSG( condition, retValue, message )
@@ -74,6 +90,9 @@
 
     This macro should be used in void functions instead of wxCHECK_MSG().
 
+    This macro should be used to catch (both in debug and release builds) logical
+    errors done by the programmer.
+
     @header{wx/debug.h}
 */
 #define wxCHECK_RET( condition, message )
@@ -85,6 +104,9 @@
     function must be done when the @c condition is @false. This check is done
     even in release mode.
 
+    This macro should be used to catch (both in debug and release builds) logical
+    errors done by the programmer.
+
     @header{wx/debug.h}
 */
 #define wxCHECK2(condition, operation)
@@ -93,6 +115,9 @@
     This is the same as wxCHECK2(), but wxFAIL_MSG() with the specified
     @c message is called instead of wxFAIL() if the @c condition is @false.
 
+    This macro should be used to catch (both in debug and release builds) logical
+    errors done by the programmer.
+
     @header{wx/debug.h}
 */
 #define wxCHECK2_MSG( condition, operation, message )
@@ -118,6 +143,8 @@
     (@c /ZI) option, so you shouldn't use it ('Program Database' (@c /Zi) is ok
     though) for the code making use of this macro.
 
+    This macro should be used to catch misconfigurations at compile-time.
+
     @see wxASSERT_MSG(), wxASSERT_MIN_BITSIZE()
 
     @header{wx/debug.h}
@@ -130,19 +157,31 @@
     macro to avoid getting the compilation errors described for
     wxCOMPILE_TIME_ASSERT().
 
+    This macro should be used to catch misconfigurations at compile-time.
+
     @header{wx/debug.h}
 */
 #define wxCOMPILE_TIME_ASSERT2(condition, message, name)
 
 /**
-    Will always generate an assert error if this code is reached (in debug
-    mode).
+    Will always generate an assert error if this code is reached (in debug mode).
+    Note that you don't have to (and cannot) use brackets when invoking this
+    macro:
+
+    @code
+        if (...some condition...) {
+            wxFAIL;
+        }
+    @endcode
+
+    This macro should be used to catch (in debug builds) logical errors done
+    by the programmer.
 
     @see wxFAIL_MSG()
 
     @header{wx/debug.h}
 */
-#define wxFAIL()
+#define wxFAIL
 
 /**
     Will always generate an assert error with specified message if this code is
@@ -152,6 +191,9 @@
     may be used in the "default:" branch of a switch statement if all possible
     cases are processed above.
 
+    This macro should be used to catch (in debug builds) logical errors done
+    by the programmer.
+
     @see wxFAIL()
 
     @header{wx/debug.h}
-- 
2.45.2