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

@@ -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
+    Will always generate an assert error if this code is reached (in debug mode).
-    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}