From: Bryan Petty <bryan@ibaku.net>
Date: Sun, 23 Mar 2008 18:24:32 +0000 (+0000)
Subject: Finished review/fixes of Math and Miscellaneous categories of functions and macros.
X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/7fa7088e4ccf5820b29ced3388e5e5b205be773a

Finished review/fixes of Math and Miscellaneous categories of functions and macros.

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

diff --git a/docs/doxygen/groups/funcmacro_math.h b/docs/doxygen/groups/funcmacro_math.h
index 30093d6314..ee726b83c6 100644
--- a/docs/doxygen/groups/funcmacro_math.h
+++ b/docs/doxygen/groups/funcmacro_math.h
@@ -11,7 +11,5 @@
 @defgroup group_funcmacro_math Math
 @ingroup group_funcmacro
 
-@header{wx/math.h}
-
 */
 
diff --git a/interface/base64.h b/interface/base64.h
index 9276bb20f1..2162513bf4 100644
--- a/interface/base64.h
+++ b/interface/base64.h
@@ -17,9 +17,9 @@
 /**
     This function encodes the given data using base64.
 
-    To allocate the buffer of the correct size, use wxBase64EncodedSize() or call
-    this function with @a dst set to @NULL -- it will then return the necessary
-    buffer size.
+    To allocate the buffer of the correct size, use wxBase64EncodedSize() or
+    call this function with @a dst set to @NULL -- it will then return the
+    necessary buffer size.
 
     This raw encoding function overload writes the output string into the
     provided buffer; the other overloads return it as a wxString.
@@ -34,33 +34,39 @@
         The length of the input data.
 
     @returns @c wxCONV_FAILED if the output buffer is too small.
+
+    @header{wx/base64.h}
 */
 size_t wxBase64Encode(char* dst, size_t dstLen,
                       const void* src,
                       size_t srcLen);
 
 /**
-    This function encodes the given data using base64 and returns the output
-    as a wxString.
+    This function encodes the given data using base64 and returns the output as
+    a wxString.
 
     There is no error return.
 
-    To allocate the buffer of the correct size, use wxBase64EncodedSize() or call
-    this function with @a dst set to @NULL -- it will then return the necessary
-    buffer size.
+    To allocate the buffer of the correct size, use wxBase64EncodedSize() or
+    call this function with @a dst set to @NULL -- it will then return the
+    necessary buffer size.
 
     @param src
         The input buffer, must not be @NULL.
     @param srcLen
         The length of the input data.
+
+    @header{wx/base64.h}
 */
 wxString wxBase64Encode(const void* src, size_t srcLen);
 
 /**
-    This function encodes the given data using base64 and returns the output
-    as a wxString.
+    This function encodes the given data using base64 and returns the output as
+    a wxString.
 
     There is no error return.
+
+    @header{wx/base64.h}
 */
 wxString wxBase64Encode(const wxMemoryBuffer& buf);
 
@@ -69,6 +75,8 @@ wxString wxBase64Encode(const wxMemoryBuffer& buf);
     Returns the size of the buffer necessary to contain the data encoded in a
     base64 string of length @e srcLen. This can be useful for allocating a
     buffer to be passed to wxBase64Decode().
+
+    @header{wx/base64.h}
 */
 size_t wxBase64DecodedSize(size_t srcLen);
 
@@ -76,32 +84,36 @@ size_t wxBase64DecodedSize(size_t srcLen);
     Returns the length of the string with base64 representation of a buffer of
     specified size @e len. This can be useful for allocating the buffer passed
     to wxBase64Encode().
+
+    @header{wx/base64.h}
 */
 size_t wxBase64EncodedSize(size_t len);
 
 /**
     This function decodes a Base64-encoded string.
 
-    This overload is a raw decoding function and decodes the data into the provided
-    buffer @a dst of the given size @e dstLen. An error is returned if the buffer
-    is not large enough -- that is not at least wxBase64DecodedSize(srcLen)() bytes.
+    This overload is a raw decoding function and decodes the data into the
+    provided buffer @a dst of the given size @e dstLen. An error is returned if
+    the buffer is not large enough -- that is not at least
+    wxBase64DecodedSize(srcLen) bytes.
 
     This overload returns the number of bytes written to the buffer or the
-    necessary buffer size if @a dst was @NULL or @c wxCONV_FAILED on
-    error, e.g. if the output buffer is too small or invalid characters were
+    necessary buffer size if @a dst was @NULL or @c wxCONV_FAILED on error,
+    e.g. if the output buffer is too small or invalid characters were
     encountered in the input string.
 
     @param dst
-        Pointer to output buffer, may be @NULL to just compute the
-        necessary buffer size.
+        Pointer to output buffer, may be @NULL to just compute the necessary
+        buffer size.
     @param dstLen
         The size of the output buffer, ignored if dst is @NULL.
     @param src
-        The input string, must not be @NULL. For the version using
-        wxString, the input string should contain only ASCII characters.
+        The input string, must not be @NULL. For the version using wxString,
+        the input string should contain only ASCII characters.
     @param srcLen
-        The length of the input string or special value wxNO_LEN if the string is
-        NUL-terminated and the length should be computed by this function itself.
+        The length of the input string or special value wxNO_LEN if the string
+        is @NULL-terminated and the length should be computed by this function
+        itself.
     @param mode
         This parameter specifies the function behaviour when invalid characters
         are encountered in input. By default, any such character stops the
@@ -109,8 +121,10 @@ size_t wxBase64EncodedSize(size_t len);
         white space characters are silently skipped instead. And if it is
         wxBase64DecodeMode_Relaxed, then all invalid characters are skipped.
     @param posErr
-        If this pointer is non-@NULL and an error occurs during
-        decoding, it is filled with the index of the invalid character.
+        If this pointer is non-@NULL and an error occurs during decoding, it is
+        filled with the index of the invalid character.
+
+    @header{wx/base64.h}
 */
 size_t wxBase64Decode(void* dst, size_t dstLen,
                       const char* src,
@@ -127,6 +141,8 @@ size_t wxBase64Decode(void* dst, size_t dstLen,
 
     This overload returns a buffer with the base64 decoded binary equivalent
     of the input string. In neither case is the buffer @NULL-terminated.
+
+    @header{wx/base64.h}
 */
 wxMemoryBuffer wxBase64Decode(const char* src,
                               size_t srcLen = wxNO_LEN,
@@ -139,6 +155,8 @@ wxMemoryBuffer wxBase64Decode(const char* src,
 
     This overload takes as input a wxString and returns the internally-allocated
     memory as a wxMemoryBuffer, containing the base64 decoded data.
+
+    @header{wx/base64.h}
 */
 wxMemoryBuffer wxBase64Decode(const wxString& src,
                               wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
diff --git a/interface/colour.h b/interface/colour.h
index 238217afd5..e7ffbb84b9 100644
--- a/interface/colour.h
+++ b/interface/colour.h
@@ -10,11 +10,10 @@
     @class wxColour
     @wxheader{colour.h}
 
-    A colour is an object representing a combination of Red, Green, and Blue (RGB)
-    intensity values,
-    and is used to determine drawing colours. See the
-    entry for wxColourDatabase for how a pointer to a predefined,
-    named colour may be returned instead of creating a new colour.
+    A colour is an object representing a combination of Red, Green, and Blue
+    (RGB) intensity values, and is used to determine drawing colours. See the
+    entry for wxColourDatabase for how a pointer to a predefined, named colour
+    may be returned instead of creating a new colour.
 
     Valid RGB values are in the range 0 to 255.
 
@@ -24,18 +23,21 @@
     @category{gdi}
 
     @stdobjects
-    ::Objects:, ::wxNullColour, ::Pointers:, ::wxBLACK, ::wxWHITE, ::wxRED,
-    ::wxBLUE, ::wxGREEN, ::wxCYAN, ::wxLIGHT_GREY,
+    ::wxNullColour, ::wxBLACK, ::wxWHITE, ::wxRED, ::wxBLUE, ::wxGREEN,
+    ::wxCYAN, ::wxLIGHT_GREY
 
     @see wxColourDatabase, wxPen, wxBrush, wxColourDialog, wxSystemSettings
 */
 class wxColour : public wxObject
 {
 public:
-    //@{
+
     /**
-        Copy constructor.
+        Default constructor.
+    */
+    wxColour();
 
+    /**
         @param red
             The red value.
         @param green
@@ -43,22 +45,22 @@ public:
         @param blue
             The blue value.
         @param alpha
-            The alpha value. Alpha values range from 0 (wxALPHA_TRANSPARENT) to 255
-        (wxALPHA_OPAQUE).
+            The alpha value. Alpha values range from 0 (wxALPHA_TRANSPARENT) to
+            255 (wxALPHA_OPAQUE).
+    */
+    wxColour(unsigned char red, unsigned char green, unsigned char blue,
+             unsigned char alpha = wxALPHA_OPAQUE);
+
+    /**
         @param colourName
             The colour name.
-        @param colour
-            The colour to copy.
+    */
+    wxColour(const wxString& colourName);
 
-        @see wxColourDatabase
+    /**
+        Copy constructor.
     */
-    wxColour();
-    wxColour(unsigned char red, unsigned char green,
-             unsigned char blue,
-             unsigned char alpha = wxALPHA_OPAQUE);
-    wxColour(const wxString& colourNname);
     wxColour(const wxColour& colour);
-    //@}
 
     /**
         Returns the alpha value, on platforms where alpha is not yet supported, this
@@ -71,24 +73,24 @@ public:
     */
     unsigned char Blue() const;
 
-    //@{
     /**
-        is not
+        Converts this colour to a wxString using the given flags.
+
+        The supported flags are wxC2S_NAME, to obtain the colour name (e.g.
+        wxColour(255,0,0) == "red"), wxC2S_CSS_SYNTAX, to obtain the colour in
+        the "rgb(r,g,b)" or "rgba(r,g,b,a)" syntax (e.g.
+        wxColour(255,0,0,85) == "rgba(255,0,0,0.333)"), and wxC2S_HTML_SYNTAX,
+        to obtain the colour as "#" followed by 6 hexadecimal digits (e.g.
+        wxColour(255,0,0) == "#FF0000").
+
+        This function never fails and always returns a non-empty string but
+        asserts if the colour has alpha channel (i.e. is non opaque) but
+        wxC2S_CSS_SYNTAX (which is the only one supporting alpha) is not
         specified in flags.
 
         @wxsince{2.7.0}
     */
     wxString GetAsString(long flags);
-    const wxC2S_NAME, to obtain the colour name (e.g.
-            wxColour(255,0,0) - "red"), wxC2S_CSS_SYNTAX, to obtain
-    the colour in the "rgb(r,g,b)" or "rgba(r,g,b,a)" syntax
-    (e.g. wxColour(255,0,0,85) - "rgba(255,0,0,0.333)"), and
-    wxC2S_HTML_SYNTAX, to obtain the colour as  "#" followed
-    by 6 hexadecimal digits (e.g. wxColour(255,0,0) - "#FF0000").
-    This function never fails and always returns a non-empty string but asserts if
-    the colour has alpha channel (i.e. is non opaque) but
-        wxC2S_CSS_SYNTAX();
-    //@}
 
     /**
         Returns a pixel value which is platform-dependent. On Windows, a COLORREF is
@@ -117,12 +119,15 @@ public:
     //@{
     /**
         Sets the RGB intensity values using the given values (first overload),
-        extracting them from the packed long (second overload), using the given string (third overloard).
+        extracting them from the packed long (second overload), using the given
+        string (third overloard).
+
         When using third form, Set() accepts: colour names (those listed in
-        wxTheColourDatabase()), the CSS-like
-        @c "rgb(r,g,b)" or @c "rgba(r,g,b,a)" syntax (case insensitive)
-        and the HTML-like syntax (i.e. @c "#" followed by 6 hexadecimal digits
-        for red, green, blue components).
+        wxTheColourDatabase()), the CSS-like @c "rgb(r,g,b)" or
+        @c "rgba(r,g,b,a)" syntax (case insensitive) and the HTML-like syntax
+        (i.e. @c "#" followed by 6 hexadecimal digits for red, green, blue
+        components).
+
         Returns @true if the conversion was successful, @false otherwise.
 
         @wxsince{2.7.0}
@@ -158,23 +163,11 @@ public:
 };
 
 
-/**
-    FIXME
-*/
-wxColour Objects:
-;
-
 /**
     FIXME
 */
 wxColour wxNullColour;
 
-/**
-    FIXME
-*/
-wxColour Pointers:
-;
-
 /**
     FIXME
 */
@@ -211,3 +204,32 @@ wxColour wxCYAN;
 wxColour wxLIGHT_GREY;
 
 
+
+// ============================================================================
+// Global functions/macros
+// ============================================================================
+
+/** @ingroup group_funcmacro_misc */
+//@{
+
+/**
+    Converts string to a wxColour best represented by the given string. Returns
+    @true on success.
+
+    @see wxToString(const wxColour&)
+
+    @header{wx/colour.h}
+*/
+bool wxFromString(const wxString& string, wxColour* colour);
+
+/**
+    Converts the given wxColour into a string.
+
+    @see wxFromString(const wxString&, wxColour*)
+
+    @header{wx/colour.h}
+*/
+wxString wxToString(const wxColour& colour);
+
+//@}
+
diff --git a/interface/cpp.h b/interface/cpp.h
index f176322202..b8585c519c 100644
--- a/interface/cpp.h
+++ b/interface/cpp.h
@@ -6,34 +6,47 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+
+/** @ingroup group_funcmacro_misc */
 //@{
 /**
-    These macro return the concatenation of the tokens passed as their arguments.
-    Unlike when using the preprocessor @c  operator, the arguments undergo
-    the macro expansion before being concatenated.
+    This macro returns the concatenation of the arguments passed. Unlike when
+    using the preprocessor operator, the arguments undergo macro expansion
+    before being concatenated.
+
+    @header{wx/cpp.h}
 */
-wxCONCAT(x1, x2);
-wxCONCAT3(x1, x2, x3);
-wxCONCAT4(x1, x2, x3, x4);
-wxCONCAT5(x1, x2, x3, x4, x5);
+#define wxCONCAT(x1, x2)
+#define wxCONCAT3(x1, x2, x3)
+#define wxCONCAT4(x1, x2, x3, x4)
+#define wxCONCAT5(x1, x2, x3, x4, x5)
 //@}
 
+/** @ingroup group_funcmacro_misc */
+//@{
 
 /**
-Returns the string representation of the given symbol which can be either a
-literal or a macro (hence the advantage of using this macro instead of the
-standard preprocessor @c # operator which doesn't work with macros).
-Notice that this macro always produces a @c char string, use
-wxSTRINGIZE_T() to build a wide string Unicode build.
+    Returns the string representation of the given symbol which can be either a
+    literal or a macro (hence the advantage of using this macro instead of the
+    standard preprocessor @c # operator which doesn't work with macros).
+
+    Notice that this macro always produces a @c char string, use
+    wxSTRINGIZE_T() to build a wide string Unicode build.
 
-@see wxCONCAT()
+    @see wxCONCAT()
+
+    @header{wx/cpp.h}
 */
-#define wxSTRINGIZE(x)     /* implementation is private */
+#define wxSTRINGIZE(x)
 
 /**
     Returns the string representation of the given symbol as either an ASCII or
-    Unicode string, depending on the current build. This is the Unicode-friendly
-    equivalent of wxSTRINGIZE().
+    Unicode string, depending on the current build. This is the
+    Unicode-friendly equivalent of wxSTRINGIZE().
+
+    @header{wx/cpp.h}
 */
-#define wxSTRINGIZE_T(x)     /* implementation is private */
+#define wxSTRINGIZE_T(x)
+
+//@}
 
diff --git a/interface/dde.h b/interface/dde.h
index 67efd41609..520508906b 100644
--- a/interface/dde.h
+++ b/interface/dde.h
@@ -314,20 +314,30 @@ public:
 // Global functions/macros
 // ============================================================================
 
+/** @ingroup group_funcmacro_misc */
+//@{
+
 /**
-    Called when wxWidgets exits, to clean up the DDE system. This no longer needs
-    to be
-    called by the application.
-    See also wxDDEInitialize().
+    Called when wxWidgets exits, to clean up the DDE system. This no longer
+    needs to be called by the application.
+
+    @see wxDDEInitialize()
+
+    @header{wx/dde.h}
 */
 void wxDDECleanUp();
 
 /**
     Initializes the DDE system. May be called multiple times without harm.
-    This no longer needs to be called by the application: it will be called
-    by wxWidgets if necessary.
-    See also wxDDEServer, wxDDEClient, wxDDEConnection,
-    wxDDECleanUp().
+
+    This no longer needs to be called by the application: it will be called by
+    wxWidgets if necessary.
+
+    @see wxDDEServer, wxDDEClient, wxDDEConnection, wxDDECleanUp()
+
+    @header{wx/dde.h}
 */
 void wxDDEInitialize();
 
+//@}
+
diff --git a/interface/debug.h b/interface/debug.h
index 8668d880aa..6338b91479 100644
--- a/interface/debug.h
+++ b/interface/debug.h
@@ -202,3 +202,19 @@ void wxTrap();
 
 //@}
 
+
+
+/** @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.
+
+    @header{wx/debug.h}
+*/
+#define __WXFUNCTION__
+
+//@}
+
diff --git a/interface/defs.h b/interface/defs.h
index 9aaed38e01..8064aab26f 100644
--- a/interface/defs.h
+++ b/interface/defs.h
@@ -67,98 +67,121 @@
 
 
 
+/** @ingroup group_funcmacro_misc */
+//@{
 
 /**
-    This macro is similar to wxDEPRECATED() but can be used
-    to not only declare the function @a func as deprecated but to also provide
-    its (inline) implementation @e body.
+    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 removed in the future) when it is used. Only Visual C++ 7 and higher and
+    g++ compilers currently support this functionality.
+
+    Example of use:
+
+    @code
+    // old function, use wxString version instead
+    wxDEPRECATED( void wxGetSomething(char *buf, size_t len) );
+
+    // ...
+    wxString wxGetSomething();
+    @endcode
+
+    @header{wx/defs.h}
+*/
+#define wxDEPRECATED(function)
+
+/**
+    This is a special version of wxDEPRECATED() macro which only does something
+    when the deprecated function is used from the code outside wxWidgets itself
+    but doesn't generate warnings when it is used from wxWidgets.
+
+    It is used with the virtual functions which are called by the library
+    itself -- even if such function is deprecated the library still has to call
+    it to ensure that the existing code overriding it continues to work, but
+    the use of this macro ensures that a deprecation warning will be generated
+    if this function is used from the user code or, in case of Visual C++, even
+    when it is simply overridden.
+
+    @header{wx/defs.h}
+*/
+#define wxDEPRECATED_BUT_USED_INTERNALLY(function)
+
+/**
+    This macro is similar to wxDEPRECATED() but can be used to not only declare
+    the function @a function as deprecated but to also provide its (inline)
+    implementation @a body.
+
     It can be used as following:
 
     @code
     class wxFoo
-        {
-        public:
-            // OldMethod() is deprecated, use NewMethod() instead
-            void NewMethod();
-            wxDEPRECATED_INLINE( void OldMethod(), NewMethod() );
-        };
+    {
+    public:
+        // OldMethod() is deprecated, use NewMethod() instead
+        void NewMethod();
+        wxDEPRECATED_INLINE( void OldMethod(), NewMethod() );
+    };
     @endcode
+
+    @header{wx/defs.h}
 */
-#define wxDEPRECATED_INLINE(func, body)     /* implementation is private */
+#define wxDEPRECATED_INLINE(func, body)
 
 /**
     @c wxEXPLICIT is a macro which expands to the C++ @c explicit keyword if
-    the compiler supports it or nothing otherwise. Thus, it can be used even in the
-    code which might have to be compiled with an old compiler without support for
-    this language feature but still take advantage of it when it is available.
-*/
+    the compiler supports it or nothing otherwise. Thus, it can be used even in
+    the code which might have to be compiled with an old compiler without
+    support for this language feature but still take advantage of it when it is
+    available.
 
+    @header{wx/defs.h}
+*/
+#define wxEXPLICIT
 
 /**
     GNU C++ compiler gives a warning for any class whose destructor is private
     unless it has a friend. This warning may sometimes be useful but it doesn't
-    make sense for reference counted class which always delete themselves (hence
-    destructor should be private) but don't necessarily have any friends, so this
-    macro is provided to disable the warning in such case. The @a name parameter
-    should be the name of the class but is only used to construct a unique friend
-    class name internally. Example of using the macro:
+    make sense for reference counted class which always delete themselves
+    (hence destructor should be private) but don't necessarily have any
+    friends, so this macro is provided to disable the warning in such case. The
+    @a name parameter should be the name of the class but is only used to
+    construct a unique friend class name internally.
+
+    Example of using the macro:
 
     @code
     class RefCounted
-        {
-        public:
-            RefCounted() { m_nRef = 1; }
-            void IncRef() { m_nRef++ ; }
-            void DecRef() { if ( !--m_nRef ) delete this; }
+    {
+    public:
+        RefCounted() { m_nRef = 1; }
+        void IncRef() { m_nRef++ ; }
+        void DecRef() { if ( !--m_nRef ) delete this; }
 
-        private:
-            ~RefCounted() { }
+    private:
+        ~RefCounted() { }
 
-            wxSUPPRESS_GCC_PRIVATE_DTOR(RefCounted)
-        };
+        wxSUPPRESS_GCC_PRIVATE_DTOR(RefCounted)
+    };
     @endcode
 
     Notice that there should be no semicolon after this macro.
-*/
-#define wxSUPPRESS_GCC_PRIVATE_DTOR_WARNING(name)     /* implementation is private */
-
-/**
-    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
-    removed in the future) when it is used. Only Visual C++ 7 and higher and g++
-    compilers currently support this functionality.
-    Example of use:
-
-    @code
-    // old function, use wxString version instead
-        wxDEPRECATED( void wxGetSomething(char *buf, size_t len) );
 
-        // ...
-        wxString wxGetSomething();
-    @endcode
+    @header{wx/defs.h}
 */
-
+#define wxSUPPRESS_GCC_PRIVATE_DTOR_WARNING(name)
 
 /**
     This macro is the same as the standard C99 @c va_copy for the compilers
-    which support it or its replacement for those that don't. It must be used to
-    preserve the value of a @c va_list object if you need to use it after
+    which support it or its replacement for those that don't. It must be used
+    to preserve the value of a @c va_list object if you need to use it after
     passing it to another function because it can be modified by the latter.
+
     As with @c va_start, each call to @c wxVaCopy must have a matching
     @c va_end.
-*/
-void wxVaCopy(va_list argptrDst, va_list argptrSrc);
 
-/**
-    This is a special version of wxDEPRECATED() macro which
-    only does something when the deprecated function is used from the code outside
-    wxWidgets itself but doesn't generate warnings when it is used from wxWidgets.
-    It is used with the virtual functions which are called by the library itself --
-    even if such function is deprecated the library still has to call it to ensure
-    that the existing code overriding it continues to work, but the use of this
-    macro ensures that a deprecation warning will be generated if this function is
-    used from the user code or, in case of Visual C++, even when it is simply
-    overridden.
+    @header{wx/defs.h}
 */
+void wxVaCopy(va_list argptrDst, va_list argptrSrc);
 
+//@}
 
diff --git a/interface/dynlib.h b/interface/dynlib.h
index 6995321611..c5abb1b599 100644
--- a/interface/dynlib.h
+++ b/interface/dynlib.h
@@ -363,24 +363,31 @@ public:
 // Global functions/macros
 // ============================================================================
 
+/** @ingroup group_funcmacro_misc */
+//@{
+
 /**
     When loading a function from a DLL you always have to cast the returned
-    @c void * pointer to the correct type and, even more annoyingly, you have to
-    repeat this type twice if you want to declare and define a function pointer all
-    in one line
+    <tt>void *</tt> pointer to the correct type and, even more annoyingly, you
+    have to repeat this type twice if you want to declare and define a function
+    pointer all in one line.
+
     This macro makes this slightly less painful by allowing you to specify the
-    type only once, as the first parameter, and creating a variable of this type
-    named after the function but with @c pfn prefix and initialized with the
-    function @a name from the wxDynamicLibrary
-    @e dynlib.
+    type only once, as the first parameter, and creating a variable of this
+    type named after the function but with @c pfn prefix and initialized with
+    the function @a name from the wxDynamicLibrary @a dynlib.
 
     @param type
-        the type of the function
+        The type of the function.
     @param name
-        the name of the function to load, not a string (without quotes,
-        it is quoted automatically by the macro)
+        The name of the function to load, not a string (without quotes, it is
+        quoted automatically by the macro).
     @param dynlib
-        the library to load the function from
+        The library to load the function from.
+
+    @header{wx/dynlib.h}
 */
-#define wxDYNLIB_FUNCTION(type, name, dynlib)     /* implementation is private */
+#define wxDYNLIB_FUNCTION(type, name, dynlib)
+
+//@}
 
diff --git a/interface/event.h b/interface/event.h
index fdb5f4fec7..22fab0484e 100644
--- a/interface/event.h
+++ b/interface/event.h
@@ -2781,11 +2781,24 @@ public:
 
 
 
+// ============================================================================
+// Global functions/macros
+// ============================================================================
+
+/** @ingroup group_funcmacro_misc */
+//@{
+
 /**
     In a GUI application, this function posts @a event to the specified @e dest
-    object using wxEvtHandler::AddPendingEvent.
+    object using wxEvtHandler::AddPendingEvent().
+
+    Otherwise, it dispatches @a event immediately using
+    wxEvtHandler::ProcessEvent(). See the respective documentation for details
+    (and caveats).
 
-    Otherwise, it dispatches @a event immediately using wxEvtHandler::ProcessEvent.
-    See the respective documentation for details (and caveats).
+    @header{wx/event.h}
 */
 void wxPostEvent(wxEvtHandler* dest, wxEvent& event);
+
+//@}
+
diff --git a/interface/font.h b/interface/font.h
index 6eea89b481..bcbe16bd90 100644
--- a/interface/font.h
+++ b/interface/font.h
@@ -654,38 +654,55 @@ public:
 /**
     FIXME
 */
-wxFont Objects:
-;
+wxFont wxNullFont;
 
 /**
     FIXME
 */
-wxFont wxNullFont;
+wxFont wxNORMAL_FONT;
 
 /**
     FIXME
 */
-wxFont Pointers:
-;
+wxFont wxSMALL_FONT;
 
 /**
     FIXME
 */
-wxFont wxNORMAL_FONT;
+wxFont wxITALIC_FONT;
 
 /**
     FIXME
 */
-wxFont wxSMALL_FONT;
+wxFont wxSWISS_FONT;
+
+
+
+// ============================================================================
+// Global functions/macros
+// ============================================================================
+
+/** @ingroup group_funcmacro_misc */
+//@{
 
 /**
-    FIXME
+    Converts string to a wxFont best represented by the given string. Returns
+    @true on success.
+
+    @see wxToString(const wxFont&)
+
+    @header{wx/font.h}
 */
-wxFont wxITALIC_FONT;
+bool wxFromString(const wxString& string, wxFont* font);
 
 /**
-    FIXME
+    Converts the given wxFont into a string.
+
+    @see wxFromString(const wxString&, wxFont*)
+
+    @header{wx/font.h}
 */
-wxFont wxSWISS_FONT;
+wxString wxToString(const wxFont& font);
 
+//@}
 
diff --git a/interface/longlong.h b/interface/longlong.h
index b67f4a623e..fc970ea8e6 100644
--- a/interface/longlong.h
+++ b/interface/longlong.h
@@ -145,6 +145,9 @@ public:
 // Global functions/macros
 // ============================================================================
 
+/** @ingroup group_funcmacro_misc */
+//@{
+
 /**
     This macro is defined to contain the @c printf() format specifier using
     which 64 bit integer numbers (i.e. those of type @c wxLongLong_t) can be
@@ -152,40 +155,48 @@ public:
 
     @code
     #ifdef wxLongLong_t
-            wxLongLong_t ll = wxLL(0x1234567890abcdef);
-            printf("Long long = %" wxLongLongFmtSpec "x\n", ll);
-        #endif
+        wxLongLong_t ll = wxLL(0x1234567890abcdef);
+        printf("Long long = %" wxLongLongFmtSpec "x\n", ll);
+    #endif
     @endcode
 
     @see wxLL()
-*/
 
+    @header{wx/longlong.h}
+*/
+#define wxLongLongFmtSpec
 
 /**
-    This macro is defined for the platforms with a native 64 bit integer type and
-    allows to define unsigned 64 bit compile time constants:
+    This macro is defined for the platforms with a native 64 bit integer type
+    and allow the use of 64 bit compile time constants:
 
     @code
     #ifdef wxLongLong_t
-            unsigned wxLongLong_t ll = wxULL(0x1234567890abcdef);
-        #endif
+        wxLongLong_t ll = wxLL(0x1234567890abcdef);
+    #endif
     @endcode
 
-    @see wxLL(), wxLongLong
+    @see wxULL(), wxLongLong
+
+    @header{wx/longlong.h}
 */
-wxLongLong_t wxULL(number);
+wxLongLong_t wxLL(number);
 
 /**
-    This macro is defined for the platforms with a native 64 bit integer type and
-    allows to define 64 bit compile time constants:
+    This macro is defined for the platforms with a native 64 bit integer type
+    and allow the use of 64 bit compile time constants:
 
     @code
     #ifdef wxLongLong_t
-            wxLongLong_t ll = wxLL(0x1234567890abcdef);
-        #endif
+        unsigned wxLongLong_t ll = wxULL(0x1234567890abcdef);
+    #endif
     @endcode
 
-    @see wxULL(), wxLongLong
+    @see wxLL(), wxLongLong
+
+    @header{wx/longlong.h}
 */
-wxLongLong_t wxLL(number);
+wxLongLong_t wxULL(number);
+
+//@}
 
diff --git a/interface/math.h b/interface/math.h
index cb05148368..e60620eaa5 100644
--- a/interface/math.h
+++ b/interface/math.h
@@ -6,10 +6,23 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+/** @ingroup group_funcmacro_math */
+//@{
+
 /**
-Returns a non-zero value if @a x is neither infinite nor NaN (not a number),
-returns 0 otherwise.
+    Returns a non-zero value if @a x is neither infinite nor NaN (not a
+    number), returns 0 otherwise.
+
+    @header{wx/math.h}
 */
 int wxFinite(double x);
 
+/**
+    Returns a non-zero value if x is NaN (not a number), returns 0 otherwise.
+
+    @header{wx/math.h}
+*/
+bool wxIsNaN(double x);
+
+//@}
 
diff --git a/interface/scopeguard.h b/interface/scopeguard.h
index 0a68edd65b..495ed93199 100644
--- a/interface/scopeguard.h
+++ b/interface/scopeguard.h
@@ -6,37 +6,41 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+/** @ingroup group_funcmacro_misc */
 //@{
 /**
-    This family of macros is similar to wxON_BLOCK_EXIT()
-    but calls a method of the given object instead of a free function.
-*/
-wxON_BLOCK_EXIT_OBJ0(obj, method);
-wxON_BLOCK_EXIT_OBJ1(obj, method, p1);
-wxON_BLOCK_EXIT_OBJ2(obj, method, p1, p2);
-//@}
-
-
-//@{
-/**
-    This family of macros allows to ensure that the global function @e func
-    with 0, 1, 2 or more parameters (up to some implementaton-defined limit) is
-    executed on scope exit, whether due to a normal function return or because an
-    exception has been thrown. A typical example of its usage:
+    This macro ensures that the global @a function with 0, 1, 2 or more
+    parameters (up to some implementaton-defined limit) is executed on scope
+    exit, whether due to a normal function return or because an exception has
+    been thrown. A typical example of its usage:
 
     @code
     void *buf = malloc(size);
-        wxON_BLOCK_EXIT1(free, buf);
+    wxON_BLOCK_EXIT1(free, buf);
     @endcode
 
     Please see the original article by Andrei Alexandrescu and Petru Marginean
-    published in December 2000 issue of C/C++ Users Journal for more
-    details.
+    published in December 2000 issue of C/C++ Users Journal for more details.
+
+    @see wxON_BLOCK_EXIT_OBJ0()
+
+    @header{wx/scopeguard.h}
+*/
+#define wxON_BLOCK_EXIT0(function)
+#define wxON_BLOCK_EXIT1(function, p1)
+#define wxON_BLOCK_EXIT2(function, p1, p2)
+//@}
+
+/** @ingroup group_funcmacro_misc */
+//@{
+/**
+    This family of macros is similar to wxON_BLOCK_EXIT0(), but calls a method
+    of the given object instead of a free function.
 
-    @see wxON_BLOCK_EXIT_OBJ()
+    @header{wx/scopeguard.h}
 */
-wxON_BLOCK_EXIT0(func);
-wxON_BLOCK_EXIT1(func, p1);
-wxON_BLOCK_EXIT2(func, p1, p2);
+#define wxON_BLOCK_EXIT_OBJ0(object, method)
+#define wxON_BLOCK_EXIT_OBJ1(object, method, p1)
+#define wxON_BLOCK_EXIT_OBJ2(object, method, p1, p2)
 //@}
 
diff --git a/interface/stockitem.h b/interface/stockitem.h
index e99dac6765..61f958d3ee 100644
--- a/interface/stockitem.h
+++ b/interface/stockitem.h
@@ -6,21 +6,26 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+/** @ingroup group_funcmacro_misc */
+//@{
+
 /**
-Returns label that should be used for given @a id element.
+    Returns label that should be used for given @a id element.
+
+    @param id
+        Given id of the wxMenuItem, wxButton, wxToolBar tool, etc.
+    @param withCodes
+        If @false then strip accelerator code from the label; useful for
+        getting labels without accelerator char code like for toolbar tooltip
+        or on platforms without traditional keyboard like smartphones.
+    @param accelerator
+        Optional accelerator string automatically added to label; useful for
+        building labels for wxMenuItem.
 
-@param id
-    given id of the wxMenuItem, wxButton, wxToolBar tool, etc.
-@param withCodes
-    if @false then strip accelerator code from the label;
-    useful for getting labels without accelerator char code like for toolbar
-tooltip or
-    on platforms without traditional keyboard like smartphones
-@param accelerator
-    optional accelerator string automatically added to label; useful
-    for building labels for wxMenuItem
+    @header{wx/stockitem.h}
 */
 wxString wxGetStockLabel(wxWindowID id, bool withCodes = true,
                          const wxString& accelerator = wxEmptyString);
 
+//@}
 
diff --git a/interface/string.h b/interface/string.h
index 973a07a489..4441581d90 100644
--- a/interface/string.h
+++ b/interface/string.h
@@ -1248,27 +1248,3 @@ public:
     wxChar* operator wxChar *();
 };
 
-
-
-// ============================================================================
-// Global functions/macros
-// ============================================================================
-
-//@{
-/**
-    Converts its argument to string.
-    See also: wxFromString().
-*/
-wxString wxToString(const wxColour& col);
-wxString wxToString(const wxFont& col);
-//@}
-
-//@{
-/**
-    Converts string to the type of the second argument. Returns @true on success.
-    See also: wxToString().
-*/
-bool wxFromString(const wxString& str, wxColour* col);
-bool wxFromString(const wxString& str, wxFont* col);
-//@}
-
diff --git a/interface/utils.h b/interface/utils.h
index 4f48f7dfc0..01cbd0b2c4 100644
--- a/interface/utils.h
+++ b/interface/utils.h
@@ -206,272 +206,323 @@ bool wxUnsetEnv(const wxString& var);
 
 
 
+/** @ingroup group_funcmacro_misc */
+//@{
+
 /**
-    Returns the type of power source as one of @c wxPOWER_SOCKET,
-    @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN.
-    @c wxPOWER_UNKNOWN is also the default on platforms where this
+    Returns battery state as one of @c wxBATTERY_NORMAL_STATE,
+    @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE,
+    @c wxBATTERY_SHUTDOWN_STATE or @c wxBATTERY_UNKNOWN_STATE.
+    @c wxBATTERY_UNKNOWN_STATE is also the default on platforms where this
     feature is not implemented (currently everywhere but MS Windows).
 
     @header{wx/utils.h}
 */
-wxPowerType wxGetPowerType();
+wxBatteryState wxGetBatteryState();
 
 /**
-    This function returns the "user id" also known as "login name" under Unix
-    i.e.  something like "jsmith". It uniquely identifies the current user (on
-    this system).  Under Windows or NT, this function first looks in the
-    environment variables USER and LOGNAME; if neither of these is found, the
-    entry @b UserId in the @b wxWidgets section of the WIN.INI file is tried.
-
-    @return Returns the login name if successful or an empty string otherwise.
-
-    @see wxGetUserName()
+    Returns the type of power source as one of @c wxPOWER_SOCKET,
+    @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN. @c wxPOWER_UNKNOWN is also the
+    default on platforms where this feature is not implemented (currently
+    everywhere but MS Windows).
 
     @header{wx/utils.h}
 */
-wxString wxGetUserId();
+wxPowerType wxGetPowerType();
 
 /**
-    @deprecated
-    This form is deprecated, use wxGetUserId() version that returns wxString.
+    Under X only, returns the current display name.
 
-    @param buf Buffer to store login name in.
-    @param sz  Size of the buffer.
+    @see wxSetDisplayName()
 
-    @return Returns @true if successful, @false otherwise.
- */
-bool wxGetUserId(char* buf, int sz);
+    @header{wx/utils.h}
+*/
+wxString wxGetDisplayName();
 
 /**
-    Returns battery state as one of @c wxBATTERY_NORMAL_STATE,
-    @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE,
-    @c wxBATTERY_SHUTDOWN_STATE or @c wxBATTERY_UNKNOWN_STATE.
-    @c wxBATTERY_UNKNOWN_STATE is also the default on platforms where
-    this feature is not implemented (currently everywhere but MS Windows).
+    For normal keys, returns @true if the specified key is currently down.
+
+    For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns @true if
+    the key is toggled such that its LED indicator is lit. There is currently
+    no way to test whether togglable keys are up or down.
+
+    Even though there are virtual key codes defined for mouse buttons, they
+    cannot be used with this function currently.
 
     @header{wx/utils.h}
 */
-wxBatteryState wxGetBatteryState();
+bool wxGetKeyState(wxKeyCode key);
 
 /**
-    @deprecated
-    This function is obsolete, please use wxWindow::FindWindowByName() instead.
-
-    Find a window by its name (as given in a window constructor or Create()
-    function call).  If @a parent is @NULL, the search will start from all
-    top-level frames and dialog boxes; if non-@NULL, the search will be limited
-    to the given window hierarchy.  The search is recursive in both cases.  If
-    no such named window is found, wxFindWindowByLabel() is called.
+    Returns the mouse position in screen coordinates.
 
     @header{wx/utils.h}
 */
-wxWindow* wxFindWindowByName(const wxString& name, wxWindow* parent = NULL);
+wxPoint wxGetMousePosition();
 
 /**
-    This function is deprecated as the ids generated by it can conflict with the
-    ids defined by the user code, use @c wxID_ANY to assign ids which are
-    guaranteed to not conflict with the user-defined ids for the controls and menu
-    items you create instead of using this function.
-
-    Generates an integer identifier unique to this run of the program.
+    Returns the current state of the mouse.  Returns a wxMouseState instance
+    that contains the current position of the mouse pointer in screen
+    coordinates, as well as boolean values indicating the up/down status of the
+    mouse buttons and the modifier keys.
 
     @header{wx/utils.h}
 */
-long wxNewId();
+wxMouseState wxGetMouseState();
 
 /**
-    Ensures that ids subsequently generated by @b NewId do not clash with
-    the given @b id.
+    This function enables or disables all top level windows. It is used by
+    wxSafeYield().
 
     @header{wx/utils.h}
 */
-void wxRegisterId(long id);
+void wxEnableTopLevelWindows(bool enable = true);
 
 /**
-    For normal keys, returns @true if the specified key is currently down.
-    For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns
-    @true if the key is toggled such that its LED indicator is lit. There is
-    currently no way to test whether togglable keys are up or down.
-    Even though there are virtual key codes defined for mouse buttons, they
-    cannot be used with this function currently.
+    Find the deepest window at the given mouse position in screen coordinates,
+    returning the window if found, or @NULL if not.
 
     @header{wx/utils.h}
 */
-bool wxGetKeyState(wxKeyCode key);
+wxWindow* wxFindWindowAtPoint(const wxPoint& pt);
 
 /**
-    Returns the string containing the description of the current platform in a
-    user-readable form. For example, this function may return strings like
-    @c Windows NT Version 4.0 or @c Linux 2.2.2 i386.
+    @deprecated Replaced by wxWindow::FindWindowByLabel().
 
-    @see ::wxGetOsVersion
+    Find a window by its label. Depending on the type of window, the label may
+    be a window title or panel item label. If @a parent is @NULL, the search
+    will start from all top-level frames and dialog boxes; if non-@NULL, the
+    search will be limited to the given window hierarchy. The search is
+    recursive in both cases.
 
     @header{wx/utils.h}
 */
-wxString wxGetOsDescription();
+wxWindow* wxFindWindowByLabel(const wxString& label,
+                              wxWindow* parent = NULL);
 
 /**
-    Return the (current) user's home directory.
+    @deprecated Replaced by wxWindow::FindWindowByName().
 
-    @see wxGetUserHome(), wxStandardPaths
+    Find a window by its name (as given in a window constructor or @e Create
+    function call). If @a parent is @NULL, the search will start from all
+    top-level frames and dialog boxes; if non-@NULL, the search will be limited
+    to the given window hierarchy. The search is recursive in both cases.
+
+    If no such named window is found, wxFindWindowByLabel() is called.
 
     @header{wx/utils.h}
 */
-wxString wxGetHomeDir();
+wxWindow* wxFindWindowByName(const wxString& name, wxWindow* parent = NULL);
 
 /**
-    Sleeps for the specified number of milliseconds. Notice that usage of this
-    function is encouraged instead of calling usleep(3) directly because the
-    standard usleep() function is not MT safe.
+    Find a menu item identifier associated with the given frame's menu bar.
 
     @header{wx/utils.h}
 */
-void wxMilliSleep(unsigned long milliseconds);
+int wxFindMenuItemId(wxFrame* frame, const wxString& menuString,
+                     const wxString& itemString);
 
 /**
-    Sleeps for the specified number of microseconds. The microsecond resolution may
-    not, in fact, be available on all platforms (currently only Unix platforms with
-    nanosleep(2) may provide it) in which case this is the same as
-    wxMilliSleep()(@e microseconds/1000).
+    @deprecated Ids generated by it can conflict with the Ids defined by the
+                user code, use @c wxID_ANY to assign ids which are guaranteed
+                to not conflict with the user-defined ids for the controls and
+                menu items you create instead of using this function.
+
+    Generates an integer identifier unique to this run of the program.
 
     @header{wx/utils.h}
 */
-void wxMicroSleep(unsigned long microseconds);
+long wxNewId();
 
+/**
+    Ensures that Ids subsequently generated by wxNewId() do not clash with the
+    given @a id.
+
+    @header{wx/utils.h}
+*/
+void wxRegisterId(long id);
 
 /**
-    Find a menu item identifier associated with the given frame's menu bar.
+    Opens the @a url in user's default browser. If the @a flags parameter
+    contains @c wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL
+    (currently this is only supported under Windows). The @a url may also be a
+    local file path (with or without the "file://" prefix), if it doesn't
+    correspond to an existing file and the URL has no scheme "http://" is
+    prepended to it by default.
+
+    Returns @true if the application was successfully launched.
+
+    @note For some configurations of the running user, the application which is
+          launched to open the given URL may be URL-dependent (e.g. a browser
+          may be used for local URLs while another one may be used for remote
+          URLs).
 
     @header{wx/utils.h}
 */
-int wxFindMenuItemId(wxFrame* frame, const wxString& menuString,
-                    const wxString& itemString);
+bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
 
 /**
-    This function enables or disables all top level windows. It is used by
-    ::wxSafeYield.
+    Loads a user-defined Windows resource as a string. If the resource is
+    found, the function creates a new character array and copies the data into
+    it. A pointer to this data is returned. If unsuccessful, @NULL is returned.
+
+    The resource must be defined in the @c .rc file using the following syntax:
+
+    @code
+    myResource TEXT file.ext
+    @endcode
+
+    Where @c file.ext is a file that the resource compiler can find.
+
+    This function is available under Windows only.
 
     @header{wx/utils.h}
 */
-void wxEnableTopLevelWindows(bool enable = true);
+wxString wxLoadUserResource(const wxString& resourceName,
+                            const wxString& resourceType = "TEXT");
 
 /**
-    Strips any menu codes from @a str and returns the result.
-    By default, the functions strips both the mnemonics character (@c '')
-    which is used to indicate a keyboard shortkey, and the accelerators, which are
-    used only in the menu items and are separated from the main text by the
-    @c \t (TAB) character. By using @a flags of
-    @c wxStrip_Mnemonics or @c wxStrip_Accel to strip only the former
-    or the latter part, respectively.
-    Notice that in most cases
-    wxMenuItem::GetLabelFromText or
-    wxControl::GetLabelText can be used instead.
+    @deprecated Replaced by wxWindow::Close(). See the
+                @ref overview_windowdeletion "window deletion overview".
+
+    Tells the system to delete the specified object when all other events have
+    been processed. In some environments, it is necessary to use this instead
+    of deleting a frame directly with the delete operator, because some GUIs
+    will still send events to a deleted window.
 
     @header{wx/utils.h}
 */
-wxString wxStripMenuCodes(const wxString& str,
-                            int flags = wxStrip_All);
+void wxPostDelete(wxObject* object);
 
 /**
-    Open the @a url in user's default browser. If @a flags parameter contains
-    @c wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL
-    (currently this is only supported under Windows). The @a url may also be a
-    local file path (with or without @c file:// prefix), if it doesn't
-    correspond to an existing file and the URL has no scheme @c http:// is
-    prepended to it by default.
-    Returns @true if the application was successfully launched.
-    Note that for some configurations of the running user, the application which
-    is launched to open the given URL may be URL-dependent (e.g. a browser may be
-    used for
-    local URLs while another one may be used for remote URLs).
+    Under X only, sets the current display name. This is the X host and display
+    name such as "colonsay:0.0", and the function indicates which display
+    should be used for creating windows from this point on. Setting the display
+    within an application allows multiple displays to be used.
+
+    @see wxGetDisplayName()
 
     @header{wx/utils.h}
 */
-bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
+void wxSetDisplayName(const wxString& displayName);
 
 /**
-    Executes a command in an interactive shell window. If no command is
-    specified, then just the shell is spawned.
-    See also wxExecute(), @ref overview_sampleexec "Exec sample".
+    Strips any menu codes from @a str and returns the result.
+
+    By default, the functions strips both the mnemonics character (@c '&')
+    which is used to indicate a keyboard shortkey, and the accelerators, which
+    are used only in the menu items and are separated from the main text by the
+    @c \t (TAB) character. By using @a flags of @c wxStrip_Mnemonics or
+    @c wxStrip_Accel to strip only the former or the latter part, respectively.
+
+    Notice that in most cases wxMenuItem::GetLabelFromText() or
+    wxControl::GetLabelText() can be used instead.
 
     @header{wx/utils.h}
 */
-bool wxShell(const wxString& command = NULL);
+wxString wxStripMenuCodes(const wxString& str, int flags = wxStrip_All);
+
+//@}
+
+
+
+
+
 
 /**
-    Gets the version and the operating system ID for currently running OS.
-    See wxPlatformInfo for more details about wxOperatingSystemId.
+    This function returns the "user id" also known as "login name" under Unix
+    i.e.  something like "jsmith". It uniquely identifies the current user (on
+    this system).  Under Windows or NT, this function first looks in the
+    environment variables USER and LOGNAME; if neither of these is found, the
+    entry @b UserId in the @b wxWidgets section of the WIN.INI file is tried.
 
-    @see ::wxGetOsDescription, wxPlatformInfo
+    @return Returns the login name if successful or an empty string otherwise.
+
+    @see wxGetUserName()
 
     @header{wx/utils.h}
 */
-wxOperatingSystemId wxGetOsVersion(int* major = NULL,
-                                    int* minor = NULL);
+wxString wxGetUserId();
 
 /**
-    Returns the FQDN (fully qualified domain host name) or an empty string on
-    error.
+    @deprecated
+    This form is deprecated, use wxGetUserId() version that returns wxString.
 
-    @see wxGetHostName()
+    @param buf Buffer to store login name in.
+    @param sz  Size of the buffer.
+
+    @return Returns @true if successful, @false otherwise.
+ */
+bool wxGetUserId(char* buf, int sz);
+
+/**
+    Returns the string containing the description of the current platform in a
+    user-readable form. For example, this function may return strings like
+    @c Windows NT Version 4.0 or @c Linux 2.2.2 i386.
+
+    @see ::wxGetOsVersion
 
     @header{wx/utils.h}
 */
-wxString wxGetFullHostName();
+wxString wxGetOsDescription();
 
 /**
-    Tells the system to delete the specified object when
-    all other events have been processed. In some environments, it is
-    necessary to use this instead of deleting a frame directly with the
-    delete operator, because some GUIs will still send events to a deleted window.
-    Now obsolete: use wxWindow::Close instead.
+    Return the (current) user's home directory.
+
+    @see wxGetUserHome(), wxStandardPaths
 
     @header{wx/utils.h}
 */
-void wxPostDelete(wxObject* object);
+wxString wxGetHomeDir();
 
 /**
-    @b NB: This function is obsolete, please use
-    wxWindow::FindWindowByLabel instead.
-    Find a window by its label. Depending on the type of window, the label may be a
-    window title
-    or panel item label. If @a parent is @NULL, the search will start from all
-    top-level
-    frames and dialog boxes; if non-@NULL, the search will be limited to the given
-    window hierarchy.
-    The search is recursive in both cases.
+    Sleeps for the specified number of milliseconds. Notice that usage of this
+    function is encouraged instead of calling usleep(3) directly because the
+    standard usleep() function is not MT safe.
 
     @header{wx/utils.h}
 */
-wxWindow* wxFindWindowByLabel(const wxString& label,
-                                wxWindow* parent = NULL);
+void wxMilliSleep(unsigned long milliseconds);
 
+/**
+    Sleeps for the specified number of microseconds. The microsecond resolution may
+    not, in fact, be available on all platforms (currently only Unix platforms with
+    nanosleep(2) may provide it) in which case this is the same as
+    wxMilliSleep()(@e microseconds/1000).
+
+    @header{wx/utils.h}
+*/
+void wxMicroSleep(unsigned long microseconds);
 
 /**
-    Returns the mouse position in screen coordinates.
+    Executes a command in an interactive shell window. If no command is
+    specified, then just the shell is spawned.
+    See also wxExecute(), @ref overview_sampleexec "Exec sample".
 
     @header{wx/utils.h}
 */
-wxPoint wxGetMousePosition();
+bool wxShell(const wxString& command = NULL);
 
 /**
-    Loads a user-defined Windows resource as a string. If the resource is found,
-    the function creates
-    a new character array and copies the data into it. A pointer to this data is
-    returned. If unsuccessful, @NULL is returned.
-    The resource must be defined in the @c .rc file using the following syntax:
+    Gets the version and the operating system ID for currently running OS.
+    See wxPlatformInfo for more details about wxOperatingSystemId.
 
-    @code
-    myResource TEXT file.ext
-    @endcode
+    @see ::wxGetOsDescription, wxPlatformInfo
 
-    where @c file.ext is a file that the resource compiler can find.
-    This function is available under Windows only.
+    @header{wx/utils.h}
+*/
+wxOperatingSystemId wxGetOsVersion(int* major = NULL,
+                                    int* minor = NULL);
+
+/**
+    Returns the FQDN (fully qualified domain host name) or an empty string on
+    error.
+
+    @see wxGetHostName()
 
     @header{wx/utils.h}
 */
-wxString wxLoadUserResource(const wxString& resourceName,
-                            const wxString& resourceType = "TEXT");
+wxString wxGetFullHostName();
 
 /**
     Returns the amount of free memory in bytes under environments which
@@ -499,13 +550,6 @@ wxString wxGetHostName();
 bool wxGetHostName(char* buf, int sz);
 //@}
 
-/**
-    Under X only, returns the current display name. See also wxSetDisplayName().
-
-    @header{wx/utils.h}
-*/
-wxString wxGetDisplayName();
-
 /**
     Returns the home directory for the given user. If the @a user is empty
     (default value), this function behaves like
@@ -702,16 +746,6 @@ unsigned long wxGetProcessId();
 int wxKill(long pid, int sig = wxSIGTERM, wxKillError rc = NULL,
             int flags = 0);
 
-/**
-    Returns the current state of the mouse.  Returns a wxMouseState
-    instance that contains the current position of the mouse pointer in
-    screen coordinates, as well as boolean values indicating the up/down
-    status of the mouse buttons and the modifier keys.
-
-    @header{wx/utils.h}
-*/
-wxMouseState wxGetMouseState();
-
 //@{
 /**
     Copies the user's email address into the supplied buffer, by
@@ -743,17 +777,3 @@ void wxSleep(int secs);
 */
 bool wxIsPlatformLittleEndian();
 
-/**
-    Under X only, sets the current display name. This is the X host and display
-    name such
-    as "colonsay:0.0", and the function indicates which display should be used for
-    creating
-    windows from this point on. Setting the display within an application allows
-    multiple
-    displays to be used.
-    See also wxGetDisplayName().
-
-    @header{wx/utils.h}
-*/
-void wxSetDisplayName(const wxString& displayName);
-
diff --git a/interface/window.h b/interface/window.h
index 2166b02de2..8b2f9d4097 100644
--- a/interface/window.h
+++ b/interface/window.h
@@ -2613,27 +2613,32 @@ public:
 // Global functions/macros
 // ============================================================================
 
-/**
-    Find the deepest window at the given mouse position in screen coordinates,
-    returning the window if found, or @NULL if not.
-*/
-wxWindow* wxFindWindowAtPoint(const wxPoint& pt);
+/** @ingroup group_funcmacro_misc */
+//@{
 
 /**
     Find the deepest window at the mouse pointer position, returning the window
     and current pointer position in screen coordinates.
+
+    @header{wx/window.h}
 */
 wxWindow* wxFindWindowAtPointer(wxPoint& pt);
 
 /**
-    Gets the currently active window (implemented for MSW and GTK only currently,
-    always returns @NULL in the other ports).
+    Gets the currently active window (implemented for MSW and GTK only
+    currently, always returns @NULL in the other ports).
+
+    @header{wx/window.h}
 */
 wxWindow* wxGetActiveWindow();
 
 /**
-    Returns the first top level parent of the given window, or in other words, the
-    frame or dialog containing it, or @NULL.
+    Returns the first top level parent of the given window, or in other words,
+    the frame or dialog containing it, or @NULL.
+
+    @header{wx/window.h}
 */
-wxWindow* wxGetTopLevelParent(wxWindow win);
+wxWindow* wxGetTopLevelParent(wxWindow* window);
+
+//@}