warn the user that for all basic classes wxPoint,wxRect,wxSize,wxRealPoint negative...

[wxWidgets.git] / interface / wx / debug.h

diff --git a/interface/wx/debug.h b/interface/wx/debug.h
index 6338b9147902b1adfc9995994f0102f1df8729c9..337ea6e4831f119f3526e68363aebe27429cf11b 100644 (file)
--- a/interface/wx/debug.h
+++ b/interface/wx/debug.h
@@ -6,15 +6,19 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
-/** @ingroup group_funcmacro_debug */
+/** @addtogroup group_funcmacro_debug */
 //@{
 
 /**
     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}
@@ -22,9 +26,11 @@
 #define wxASSERT( condition )
 
 /**
-    This macro results in a
-    @ref overview_wxcompiletimeassert "compile time assertion failure" if the
-    size of the given @c type is less than @c size bits.
+    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:
 
@@ -41,8 +47,11 @@
 #define wxASSERT_MIN_BITSIZE( type, size )
 
 /**
-    Assert macro with message. An error message will be generated if the
-    condition is @false.
+    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()
 
@@ -52,8 +61,10 @@
 
 /**
     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.
+    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}
 */
@@ -61,11 +72,13 @@
 
 /**
     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.
+    not (stops execution in debug mode). This check is done even in release mode.
 
     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 )
@@ -77,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 )
@@ -88,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)
@@ -96,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 )
@@ -121,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}
@@ -133,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
@@ -155,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}
@@ -204,7 +243,7 @@ void wxTrap();
 
 
 
-/** @ingroup group_funcmacro_misc */
+/** @addtogroup group_funcmacro_misc */
 //@{
 
 /**