Categorized all functions and macros in the Debugging and Version categories.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52538 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/doxygen/groups/funcmacro_debug.h

@@ -12,15 +12,13 @@
 @ingroup group_funcmacro
 
 Useful macros and functions for error checking and defensive programming.
-wxWidgets defines three families of the assert-like macros: the wxASSERT and
+wxWidgets defines three families of the assert-like macros: the wxASSERT() and
-wxFAIL macros only do anything if __WXDEBUG__ is defined (in other words, in
+wxFAIL() macros only do anything if __WXDEBUG__ is defined (in other words, in
 the debug build) but disappear completely in the release build. On the other
-hand, the wxCHECK macros stay event in release builds but a check failure
+hand, the wxCHECK() macros stay in release builds but a check failure doesn't
-doesn't generate any user-visible effects then. Finally, the compile time
+generate any user-visible effects. Finally, the compile time assertions don't
-assertions don't happen during the run-time but result in the compilation error
+happen during the run-time but result in the compilation error messages if the
-messages if the condition they check fail.
+condition they check fail.
-
-@header{wx/debug.h}
 
 */
 

docs/doxygen/groups/funcmacro_version.h

@@ -32,7 +32,6 @@ The subrelease number is only used for the sources in between official releases
 and so normally is not useful.
 
 @header{wx/version.h}
-@header{wx/defs.h}
 
 */
 

interface/debug.h

@@ -6,84 +6,8 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
-/**
+/** @ingroup group_funcmacro_debug */
-Will always generate an assert error if this code is reached (in debug mode).
+//@{
-See also: wxFAIL_MSG()
-*/
-wxFAIL();
-
-
-/**
-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.
-*/
-void wxOnAssert(const char* fileName, int lineNumber,
-                const char* func,
-                const char* cond,
-                const char* msg = NULL);
-
-/**
-    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.
-*/
-void wxTrap();
-
-/**
-    Will always generate an assert error with specified message if this code is
-    reached (in debug 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.
-
-    @see wxFAIL()
-*/
-#define wxFAIL_MSG(msg)     /* implementation is private */
-
-/**
-    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.
-*/
-#define wxCHECK(condition, retValue)     /* implementation is private */
-
-/**
-    This macro results in a
-    @ref overview_wxcompiletimeassert "compile time assertion failure" if the size
-    of the given type @a type is less than @a 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
-*/
-#define wxASSERT_MIN_BITSIZE(type, size)     /* implementation is private */
-
-/**
-    Assert macro with message. An error message will be generated if the condition
-    is @false.
-
-    @see wxASSERT(), wxCOMPILE_TIME_ASSERT()
-*/
-#define wxASSERT_MSG(condition, msg)     /* implementation is private */
-
-/**
-    This is the same as wxCHECK2(), but
-    wxFAIL_MSG() with the specified @a msg is called
-    instead of wxFAIL() if the @a condition is @false.
-*/
-#define wxCHECK2(condition, operation, msg)     /* implementation is private */
 
 /**
     Assert macro. An error message will be generated if the condition is @false in
@@ -92,62 +16,189 @@ void wxTrap();
     because it will not be executed in release mode at all.
 
     @see wxASSERT_MSG(), wxCOMPILE_TIME_ASSERT()
+
+    @header{wx/debug.h}
 */
-#define wxASSERT(condition)     /* implementation is private */
+#define wxASSERT( condition )
 
 /**
-    Checks that the condition is @true, and returns if not (FAILs with given error
+    This macro results in a
-    message in debug mode). This check is done even in release mode.
+    @ref overview_wxcompiletimeassert "compile time assertion failure" if the
-    This macro should be used in void functions instead of
+    size of the given @c type is less than @c size bits.
-    wxCHECK_MSG().
+
+    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 wxCHECK_RET(condition, msg)     /* implementation is private */
+#define wxASSERT_MIN_BITSIZE( type, size )
 
 /**
-    Checks that the condition is @true and wxFAIL() and execute
+    Assert macro with message. An error message will be generated if the
-    @a operation if it is not. This is a generalisation of
+    condition is @false.
-    wxCHECK() and may be used when something else than just
+
-    returning from the function must be done when the @a condition is @false.
+    @see wxASSERT(), wxCOMPILE_TIME_ASSERT()
-    This check is done even in release mode.
+
+    @header{wx/debug.h}
 */
-#define wxCHECK2(condition, operation)     /* implementation is private */
+#define wxASSERT_MSG( condition, message )
 
 /**
-    This macro is identical to wxCOMPILE_TIME_ASSERT2()
+    Checks that the condition is @true, returns with the given return value if
-    except that it allows you to specify a unique @a name for the struct
+    not (stops execution in debug mode). This check is done even in release
-    internally defined by this macro to avoid getting the compilation errors
+    mode.
-    described above().
+
+    @header{wx/debug.h}
 */
-#define wxCOMPILE_TIME_ASSERT(condition, msg, name)     /* implementation is private */
+#define wxCHECK( condition, retValue )
 
 /**
-    Checks that the condition is @true, returns with the given return value if not
+    Checks that the condition is @true, returns with the given return value if
-    (FAILs in debug mode).
+    not (stops execution in debug mode). This check is done even in release
-    This check is done even in release mode.
+    mode.
-    This macro may be only used in non-void functions, see also
+
-    wxCHECK_RET().
+    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 */
+#define wxCHECK_MSG( condition, retValue, message )
 
 /**
-    Using @c wxCOMPILE_TIME_ASSERT results in a compilation error if the
+    Checks that the condition is @true, and returns if not (stops execution
-    specified @a condition is @false. The compiler error message should include
+    with the given error message in debug mode). This check is done even in
-    the @a msg identifier - please note that it must be a valid C++ identifier
+    release mode.
-    and not a string unlike in the other cases.
+
+    This macro should be used in void functions instead of wxCHECK_MSG().
+
+    @header{wx/debug.h}
+*/
+#define wxCHECK_RET( condition, message )
+
+/**
+    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.
+
+    @header{wx/debug.h}
+*/
+#define wxCHECK2(condition, operation)
+
+/**
+    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 wxCHECK2_MSG( condition, operation, message )
+
+/**
+    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.
+
     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
+    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'
+    Also note that Microsoft Visual C++ has a bug which results in compiler
-    (@c /ZI) option, so you shouldn't use it ('Program Database'
+    errors if you use this macro with 'Program Database For Edit And Continue'
-    (@c /Zi) is ok though) for the code making use of this macro.
+    (@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()
-*/
+
-#define wxCOMPILE_TIME_ASSERT(condition, msg)     /* implementation is private */
+    @header{wx/debug.h}
+*/
+#define wxCOMPILE_TIME_ASSERT( condition, message )
+
+/**
+    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 wxCOMPILE_TIME_ASSERT2(condition, message, name)
+
+/**
+    Will always generate an assert error if this code is reached (in debug
+    mode).
+
+    @see wxFAIL_MSG()
+
+    @header{wx/debug.h}
+*/
+#define wxFAIL()
+
+/**
+    Will always generate an assert error with specified message if this code is
+    reached (in debug 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.
+
+    @see wxFAIL()
+
+    @header{wx/debug.h}
+*/
+#define wxFAIL_MSG( message )
+
+/**
+    Returns @true if the program is running under debugger, @false otherwise.
+
+    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}
+*/
+bool wxIsDebuggerRunning();
+
+/**
+    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}
+*/
+void wxOnAssert( const char* fileName,
+                  int lineNumber,
+                  const char* function,
+                  const char* condition,
+                  const char* message = NULL );
+
+/**
+    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.
+
+    @header{wx/debug.h}
+*/
+void wxTrap();
+
+//@}
 

interface/defs.h

@@ -6,34 +6,68 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+/** @ingroup group_funcmacro_byteorder */
 //@{
+
 /**
-    These macros will swap the bytes of the @a value variable from little
+    This macro will swap the bytes of the @a value variable from little endian
-    endian to big endian or vice versa unconditionally, i.e. independently of the
+    to big endian or vice versa unconditionally, i.e. independently of the
     current platform.
+
+    @header{wx/defs.h}
 */
-wxInt32 wxINT32_SWAP_ALWAYS(wxInt32 value);
+#define wxINT32_SWAP_ALWAYS( wxInt32 value )
-wxUint32 wxUINT32_SWAP_ALWAYS(wxUint32 value);
+#define wxUINT32_SWAP_ALWAYS( wxUint32 value )
-wxInt16 wxINT16_SWAP_ALWAYS(wxInt16 value);
+#define wxINT16_SWAP_ALWAYS( wxInt16 value )
-wxUint16 wxUINT16_SWAP_ALWAYS(wxUint16 value);
+#define wxUINT16_SWAP_ALWAYS( wxUint16 value )
+
 //@}
 
-
+/** @ingroup group_funcmacro_byteorder */
 //@{
+
 /**
-    This macro will swap the bytes of the @a value variable from little
+    This macro will swap the bytes of the @a value variable from little endian
-    endian to big endian or vice versa if the program is compiled on a
+    to big endian or vice versa if the program is compiled on a big-endian
-    little-endian architecture (such as Intel PCs). If the program has
+    architecture (such as Sun work stations). If the program has been compiled
-    been compiled on a big-endian architecture, the value will be unchanged.
+    on a little-endian architecture, the value will be unchanged.
+
+    Use these macros to read data from and write data to a file that stores
+    data in little-endian (for example Intel i386) format.
+
+    @header{wx/defs.h}
+*/
+#define wxINT32_SWAP_ON_BE( wxInt32 value )
+#define wxUINT32_SWAP_ON_BE( wxUint32 value )
+#define wxINT16_SWAP_ON_BE( wxInt16 value )
+#define wxUINT16_SWAP_ON_BE( wxUint16 value )
+
+//@}
+
+/** @ingroup group_funcmacro_byteorder */
+//@{
+
+/**
+    This macro will swap the bytes of the @a value variable from little endian
+    to big endian or vice versa if the program is compiled on a little-endian
+    architecture (such as Intel PCs). If the program has been compiled on a
+    big-endian architecture, the value will be unchanged.
+
     Use these macros to read data from and write data to a file that stores
     data in big-endian format.
+
+    @header{wx/defs.h}
 */
-wxInt32 wxINT32_SWAP_ON_LE(wxInt32 value);
+#define wxINT32_SWAP_ON_LE( wxInt32 value )
-wxUint32 wxUINT32_SWAP_ON_LE(wxUint32 value);
+#define wxUINT32_SWAP_ON_LE( wxUint32 value )
-wxInt16 wxINT16_SWAP_ON_LE(wxInt16 value);
+#define wxINT16_SWAP_ON_LE( wxInt16 value )
-wxUint16 wxUINT16_SWAP_ON_LE(wxUint16 value);
+#define wxUINT16_SWAP_ON_LE( wxUint16 value )
+
 //@}
 
+
+
+
 /**
     This macro is similar to wxDEPRECATED() but can be used
     to not only declare the function @a func as deprecated but to also provide
@@ -88,21 +122,6 @@ wxUint16 wxUINT16_SWAP_ON_LE(wxUint16 value);
 */
 #define wxSUPPRESS_GCC_PRIVATE_DTOR_WARNING(name)     /* implementation is private */
 
-//@{
-/**
-    This macro will swap the bytes of the @a value variable from little
-    endian to big endian or vice versa if the program is compiled on a
-    big-endian architecture (such as Sun work stations). If the program has
-    been compiled on a little-endian architecture, the value will be unchanged.
-    Use these macros to read data from and write data to a file that stores
-    data in little-endian (for example Intel i386) format.
-*/
-wxInt32 wxINT32_SWAP_ON_BE(wxInt32 value);
-wxUint32 wxUINT32_SWAP_ON_BE(wxUint32 value);
-wxInt16 wxINT16_SWAP_ON_BE(wxInt16 value);
-wxUint16 wxUINT16_SWAP_ON_BE(wxUint16 value);
-//@}
-
 /**
     This macro can be used around a function declaration to generate warnings
     indicating that this function is deprecated (i.e. obsolete and planned to be

interface/link.h

@@ -6,27 +6,35 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
-/**
+/** @ingroup group_funcmacro_byteorder */
-This macro can be used in conjunction with the
+//@{
-wxFORCE_LINK_MODULE() macro to force
-the linker to include in its output a specific object file.
-In particular, you should use this macro in the source file which you want
-to force for inclusion. The @c moduleName needs to be a name not already
-in use in other @c wxFORCE_LINK_THIS_MODULE macros, but is not required
-to be e.g. the same name of the source file (even if it's a good choice).
-*/
-#define wxFORCE_LINK_THIS_MODULE()     /* implementation is private */
-
 
 /**
-This macro can be used in conjunction with the
+    This macro can be used in conjunction with the wxFORCE_LINK_MODULE() macro
-wxFORCE_LINK_THIS_MODULE() macro to force
+    to force the linker to include in its output a specific object file.
-the linker to include in its output a specific object file.
+    
-In particular, you should use this macro in a source file which you know
+    In particular, you should use this macro in the source file which you want
-for sure is linked in the output (e.g. the source file containing the "main()"
+    to force for inclusion. The @c moduleName needs to be a name not already in
-of your app). The @c moduleName is the name of the module you want to
+    use in other wxFORCE_LINK_THIS_MODULE() macros, but is not required to be
-forcefully link
+    e.g. the same name of the source file (even if it's a good choice).
-(i.e. the name you used in the relative wxFORCE_LINK_THIS_MODULE() macro.
+
-*/
+    @header{wx/link.h}
-#define wxFORCE_LINK_MODULE()     /* implementation is private */
+*/
+#define wxFORCE_LINK_THIS_MODULE( moduleName )
+
+/**
+    This macro can be used in conjunction with the wxFORCE_LINK_THIS_MODULE()
+    macro to force the linker to include in its output a specific object file.
+    
+    In particular, you should use this macro in a source file which you know
+    for sure is linked in the output (e.g. the source file containing the
+    @c main() of your app). The @c moduleName is the name of the module you
+    want to forcefully link (i.e. the name you used in the relative
+    wxFORCE_LINK_THIS_MODULE() macro.
+
+    @header{wx/link.h}
+*/
+#define wxFORCE_LINK_MODULE( moduleName )
+
+//@}
 

interface/platform.h

@@ -12,18 +12,24 @@
 /**
     Returns @true if the compiler being used is GNU C++ and its version is
     at least major.minor or greater. Returns @false otherwise.
+
+    @header{wx/platform.h}
 */
 #define wxCHECK_GCC_VERSION( major, minor )
 
 /**
     Returns @true if the compiler being used is Sun CC Pro and its version is
     at least major.minor or greater. Returns @false otherwise.
+
+    @header{wx/platform.h}
 */
 #define wxCHECK_SUNCC_VERSION( major, minor )
 
 /**
     Returns @true if the compiler being used is Visual C++ and its version is
     at least major or greater. Returns @false otherwise.
+
+    @header{wx/platform.h}
 */
 #define wxCHECK_VISUALC_VERSION( major )
 
@@ -31,6 +37,8 @@
     Returns @true if the version of w32api headers used is major.minor or
     greater. Otherwise, and also if we are not compiling with MinGW32/Cygwin
     under Win32 at all, returns @false.
+
+    @header{wx/platform.h}
 */
 #define wxCHECK_W32API_VERSION( major, minor )
 

interface/version.h

@@ -27,12 +27,16 @@
             ...
         }
     @endcode
+
+    @header{wx/version.h}
 */
 #define wxCHECK_VERSION( major, minor, release )
 
 /**
     Same as wxCHECK_VERSION() but also checks that wxSUBRELEASE_NUMBER is at
     least subrel.
+
+    @header{wx/version.h}
 */
 #define wxCHECK_VERSION_FULL( major, minor, release, subrel )