Minor correction

[wxWidgets.git] / interface / debug.h

diff --git a/interface/debug.h b/interface/debug.h
index 4420ad5db250fad43472ef0417060a2ec47d83dc..6338b9147902b1adfc9995994f0102f1df8729c9 100644 (file)
--- a/interface/debug.h
+++ b/interface/debug.h
@@ -1,164 +1,220 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        debug.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        debug.h

-// Purpose:     documentation for global functions
+// Purpose:     interface of global functions

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+/** @ingroup group_funcmacro_debug */
+//@{
+

 /**
 /**

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

 
 

-See also: wxFAIL_MSG
+    @see wxASSERT_MSG(), wxCOMPILE_TIME_ASSERT()
+
+    @header{wx/debug.h}

 */
 */

-#define wxFAIL()     /* implementation is private */
+#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.

 
 

+    You may use it like this, for example:
+
+    @code
+    // we rely on the int being able to hold values up to 2^32
+    wxASSERT_MIN_BITSIZE(int, 32);
+
+    // can't work with the platforms using UTF-8 for wchar_t
+    wxASSERT_MIN_BITSIZE(wchar_t, 16);
+    @endcode
+
+    @header{wx/debug.h}
+*/
+#define wxASSERT_MIN_BITSIZE( type, size )

 
 /**
 
 /**

-This function is called whenever one of debugging macros fails (i.e. condition
-is @false in an assertion). It is only defined in the debug mode, in release
-builds the wxCHECK failures don't result in anything.
+    Assert macro with message. An error message will be generated if the
+    condition is @false.

 
 

-To override the default behaviour in the debug builds which is to show the user
-a dialog asking whether he wants to abort the program, continue or continue
-ignoring any subsequent assert failures, you may override
-wxApp::OnAssertFailure which is called by this function if
-the global application object exists.
+    @see wxASSERT(), wxCOMPILE_TIME_ASSERT()
+
+    @header{wx/debug.h}

 */
 */

-void wxOnAssert(const char * fileName, int lineNumber,
-                const char * func,
-                const char * cond,
-                const char * msg = @NULL);
+#define wxASSERT_MSG( condition, message )

 
 /**
 
 /**

-    In debug mode (when @c __WXDEBUG__ is defined) this function generates a
-    debugger exception meaning that the control is passed to the debugger if one is
-    attached to the process. Otherwise the program just terminates abnormally.
+    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.

 
 

-    In release mode this function does nothing.
+    @header{wx/debug.h}

 */
 */

-void wxTrap();
+#define wxCHECK( condition, retValue )

 
 /**
 
 /**

-    Will always generate an assert error with specified message if this code is
-    reached (in debug mode).
+    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 is useful for marking unreachable" code areas, for example
-    it may be used in the "default:" branch of a switch statement if all possible
-    cases are processed above.
+    This macro may be only used in non-void functions, see also wxCHECK_RET().

 
 

-    @sa wxFAIL
+    @header{wx/debug.h}

 */
 */

-#define wxFAIL_MSG(msg)     /* implementation is private */
+#define wxCHECK_MSG( condition, retValue, message )

 
 /**
 
 /**

-    Checks that the condition is @true, returns with the given return value if not
-    (FAILs in debug mode).
-    This check is done even in release mode.
+    Checks that the condition is @true, and returns if not (stops execution
+    with the given error message in debug mode). This check is done even in
+    release mode.
+
+    This macro should be used in void functions instead of wxCHECK_MSG().
+
+    @header{wx/debug.h}

 */
 */

-#define wxCHECK(condition,  retValue)     /* implementation is private */
+#define wxCHECK_RET( condition, message )

 
 /**
 
 /**

-    This macro results in a
-    @ref overview_wxcompiletimeassert "compile time assertion failure" if the size
-    of the given type @e type is less than @e size bits.
+    Checks that the condition is @true, and if not, it will wxFAIL() and
+    execute the given @c operation if it is not. This is a generalisation of
+    wxCHECK() and may be used when something else than just returning from the
+    function must be done when the @c condition is @false. This check is done
+    even in release mode.

 
 

-    You may use it like this, for example:
-    @code
-    // we rely on the int being able to hold values up to 2^32
-        wxASSERT_MIN_BITSIZE(int, 32);
+    @header{wx/debug.h}
+*/
+#define wxCHECK2(condition, operation)

 
 

-        // can't work with the platforms using UTF-8 for wchar_t
-        wxASSERT_MIN_BITSIZE(wchar_t, 16);
-    @endcode
+/**
+    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.
+
+    @header{wx/debug.h}

 */
 */

-#define wxASSERT_MIN_BITSIZE(type,  size)     /* implementation is private */
+#define wxCHECK2_MSG( condition, operation, message )

 
 /**
 
 /**

-    Assert macro with message. An error message will be generated if the condition
-    is @false.
+    Using wxCOMPILE_TIME_ASSERT() results in a compilation error if the
+    specified @c condition is @false. The compiler error message should include
+    the @c message identifier - please note that it must be a valid C++
+    identifier and not a string unlike in the other cases.

 
 

-    @sa wxASSERT, wxCOMPILE_TIME_ASSERT
+    This macro is mostly useful for testing the expressions involving the
+    @c sizeof operator as they can't be tested by the preprocessor but it is
+    sometimes desirable to test them at the compile time.
+
+    Note that this macro internally declares a struct whose name it tries to
+    make unique by using the @c __LINE__ in it but it may still not work if you
+    use it on the same line in two different source files. In this case you may
+    either change the line in which either of them appears on or use the
+    wxCOMPILE_TIME_ASSERT2() macro.
+
+    Also note that Microsoft Visual C++ has a bug which results in compiler
+    errors if you use this macro with 'Program Database For Edit And Continue'
+    (@c /ZI) option, so you shouldn't use it ('Program Database' (@c /Zi) is ok
+    though) for the code making use of this macro.
+
+    @see wxASSERT_MSG(), wxASSERT_MIN_BITSIZE()
+
+    @header{wx/debug.h}

 */
 */

-#define wxASSERT_MSG(condition,  msg)     /* implementation is private */
+#define wxCOMPILE_TIME_ASSERT( condition, message )

 
 /**
 
 /**

-    This is the same as wxCHECK2, but
-    wxFAIL_MSG with the specified @e msg is called
-    instead of wxFAIL() if the @e condition is @false.
+    This macro is identical to wxCOMPILE_TIME_ASSERT() except that it allows
+    you to specify a unique @c name for the struct internally defined by this
+    macro to avoid getting the compilation errors described for
+    wxCOMPILE_TIME_ASSERT().
+
+    @header{wx/debug.h}

 */
 */

-#define wxCHECK2(condition,  operation,  msg)     /* implementation is private */
+#define wxCOMPILE_TIME_ASSERT2(condition, message, name)

 
 /**
 
 /**

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

 
 

-    Please note that the condition in wxASSERT() should have no side effects
-    because it will not be executed in release mode at all.
+    @see wxFAIL_MSG()

 
 

-    @sa wxASSERT_MSG, wxCOMPILE_TIME_ASSERT
+    @header{wx/debug.h}

 */
 */

-#define wxASSERT(condition)     /* implementation is private */
+#define wxFAIL()

 
 /**
 
 /**

-    Checks that the condition is @true, and returns if not (FAILs with given error
-    message in debug mode). This check is done even in release mode.
+    Will always generate an assert error with specified message if this code is
+    reached (in debug mode).

 
 

-    This macro should be used in void functions instead of
-    wxCHECK_MSG.
+    This macro is useful for marking unreachable" code areas, for example it
+    may be used in the "default:" branch of a switch statement if all possible
+    cases are processed above.
+
+    @see wxFAIL()
+
+    @header{wx/debug.h}

 */
 */

-#define wxCHECK_RET(condition,  msg)     /* implementation is private */
+#define wxFAIL_MSG( message )

 
 /**
 
 /**

-    Checks that the condition is @true and wxFAIL and execute
-    @e operation if it is not. This is a generalisation of
-    wxCHECK and may be used when something else than just
-    returning from the function must be done when the @e condition is @false.
+    Returns @true if the program is running under debugger, @false otherwise.

 
 

-    This check is done even in release mode.
+    Please note that this function is currently only implemented for Win32 and
+    Mac builds using CodeWarrior and always returns @false elsewhere.
+
+    @header{wx/debug.h}

 */
 */

-#define wxCHECK2(condition,  operation)     /* implementation is private */
+bool wxIsDebuggerRunning();

 
 /**
 
 /**

-    This macro is identical to wxCOMPILE_TIME_ASSERT2
-    except that it allows you to specify a unique @e name for the struct
-    internally defined by this macro to avoid getting the compilation errors
-    described above.
+    This function is called whenever one of debugging macros fails (i.e.
+    condition is @false in an assertion). It is only defined in the debug mode,
+    in release builds the wxCHECK() failures don't result in anything.
+
+    To override the default behaviour in the debug builds which is to show the
+    user a dialog asking whether he wants to abort the program, continue or
+    continue ignoring any subsequent assert failures, you may override
+    wxApp::OnAssertFailure() which is called by this function if the global
+    application object exists.
+
+    @header{wx/debug.h}

 */
 */

-#define wxCOMPILE_TIME_ASSERT(condition,  msg,  name)     /* implementation is private */
+void wxOnAssert( const char* fileName,
+                  int lineNumber,
+                  const char* function,
+                  const char* condition,
+                  const char* message = NULL );

 
 /**
 
 /**

-    Checks that the condition is @true, returns with the given return value if not
-    (FAILs in debug mode).
-    This check is done even in release mode.
+    In debug mode (when @c __WXDEBUG__ is defined) this function generates a
+    debugger exception meaning that the control is passed to the debugger if
+    one is attached to the process. Otherwise the program just terminates
+    abnormally. In release mode this function does nothing.

 
 

-    This macro may be only used in non-void functions, see also
-    wxCHECK_RET.
+    @header{wx/debug.h}

 */
 */

-#define wxCHECK_MSG(condition,  retValue,  msg)     /* implementation is private */
+void wxTrap();

 
 

-/**
-    Using @c wxCOMPILE_TIME_ASSERT results in a compilation error if the
-    specified @e condition is @false. The compiler error message should include
-    the @e msg identifier - please note that it must be a valid C++ identifier
-    and not a string unlike in the other cases.
+//@}

 
 

-    This macro is mostly useful for testing the expressions involving the
-    @c sizeof operator as they can't be tested by the preprocessor but it is
-    sometimes desirable to test them at the compile time.

 
 

-    Note that this macro internally declares a struct whose name it tries to make
-    unique by using the @c __LINE__ in it but it may still not work if you
-    use it on the same line in two different source files. In this case you may
-    either change the line in which either of them appears on or use the
-    wxCOMPILE_TIME_ASSERT2 macro.

 
 

-    Also note that Microsoft Visual C++ has a bug which results in compiler errors
-    if you use this macro with 'Program Database For Edit And Continue'
-    (@c /ZI) option, so you shouldn't use it ('Program Database'
-    (@c /Zi) is ok though) for the code making use of this macro.
+/** @ingroup group_funcmacro_misc */
+//@{
+
+/**
+    This macro expands to the name of the current function if the compiler
+    supports any of @c __FUNCTION__, @c __func__ or equivalent variables or
+    macros or to @NULL if none of them is available.

 
 

-    @sa wxASSERT_MSG, wxASSERT_MIN_BITSIZE
+    @header{wx/debug.h}

 */
 */

-#define wxCOMPILE_TIME_ASSERT(condition,  msg)     /* implementation is private */
+#define __WXFUNCTION__
+
+//@}