Finished initial review of a few [g*] interface headers.

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

interface/cursor.h

@@ -79,7 +79,8 @@
     - ::wxHOURGLASS_CURSOR
     - ::wxCROSS_CURSOR
 
-    @see wxBitmap, wxIcon, wxWindow::SetCursor(), wxSetCursor()
+    @see wxBitmap, wxIcon, wxWindow::SetCursor(), wxSetCursor(),
+         ::wxStockCursor
 */
 class wxCursor : public wxBitmap
 {
@@ -153,42 +154,9 @@ public:
         Constructs a cursor using a cursor identifier.
 
         @param cursorId
-            A stock cursor identifier. May be one of the following (note that
+            A stock cursor identifier. See ::wxStockCursor.
-            not all cursors are available on all platforms):
-            - wxCURSOR_ARROW          - A standard arrow cursor.
-            - wxCURSOR_RIGHT_ARROW    - A standard arrow cursor pointing to the
-                                        right.
-            - wxCURSOR_BLANK          - Transparent cursor.
-            - wxCURSOR_BULLSEYE       - Bullseye cursor.
-            - wxCURSOR_CHAR           - Rectangular character cursor.
-            - wxCURSOR_CROSS          - A cross cursor.
-            - wxCURSOR_HAND           - A hand cursor.
-            - wxCURSOR_IBEAM          - An I-beam cursor (vertical line).
-            - wxCURSOR_LEFT_BUTTON    - Represents a mouse with the left button
-                                        depressed.
-            - wxCURSOR_MAGNIFIER      - A magnifier icon.
-            - wxCURSOR_MIDDLE_BUTTON  - Represents a mouse with the middle
-                                        button depressed.
-            - wxCURSOR_NO_ENTRY       - A no-entry sign cursor.
-            - wxCURSOR_PAINT_BRUSH    - A paintbrush cursor.
-            - wxCURSOR_PENCIL         - A pencil cursor.
-            - wxCURSOR_POINT_LEFT     - A cursor that points left.
-            - wxCURSOR_POINT_RIGHT    - A cursor that points right.
-            - wxCURSOR_QUESTION_ARROW - An arrow and question mark.
-            - wxCURSOR_RIGHT_BUTTON   - Represents a mouse with the right
-                                        button depressed.
-            - wxCURSOR_SIZENESW       - A sizing cursor pointing NE-SW.
-            - wxCURSOR_SIZENS         - A sizing cursor pointing N-S.
-            - wxCURSOR_SIZENWSE       - A sizing cursor pointing NW-SE.
-            - wxCURSOR_SIZEWE         - A sizing cursor pointing W-E.
-            - wxCURSOR_SIZING         - A general sizing cursor.
-            - wxCURSOR_SPRAYCAN       - A spraycan cursor.
-            - wxCURSOR_WAIT           - A wait cursor.
-            - wxCURSOR_WATCH          - A watch cursor.
-            - wxCURSOR_ARROWWAIT      - A cursor with both an arrow and an
-                                        hourglass, (windows.)
     */
-    wxCursor(int cursorId);
+    wxCursor(wxStockCursor cursorId);
     /**
         Constructs a cursor from a wxImage. If cursor are monochrome on the
         current platform, colors with the RGB elements all greater than 127
@@ -238,7 +206,11 @@ public:
 };
 
 
-/** @name Predefined cursors. */
+/**
+    @name Predefined cursors.
+
+    @see wxStockCursor
+*/
 //@{
 wxCursor wxNullCursor;
 wxCursor* wxSTANDARD_CURSOR;

interface/gauge.h

@@ -10,17 +10,17 @@
     @class wxGauge
     @wxheader{gauge.h}
 
-    A gauge is a horizontal or vertical bar which shows a quantity (often time).
+    A gauge is a horizontal or vertical bar which shows a quantity (often
+    time).
 
     wxGauge supports two working modes: determinate and indeterminate progress.
 
-    The first is the usual working mode (see wxGauge::SetValue
+    The first is the usual working mode (see SetValue() and SetRange()) while
-    and wxGauge::SetRange) while the second can be used when
+    the second can be used when the program is doing some processing but you
-    the program is doing some processing but you don't know how much progress is
+    don't know how much progress is being done. In this case, you can
-    being done.
+    periodically call the Pulse() function to make the progress bar switch to
-    In this case, you can periodically call the wxGauge::Pulse
+    indeterminate mode (graphically it's usually a set of blocks which move or
-    function to make the progress bar switch to indeterminate mode (graphically
+    bounce in the bar control).
-    it's usually a set of blocks which move or bounce in the bar control).
 
     wxGauge supports dynamic switch between these two work modes.
 
@@ -38,14 +38,17 @@
 
     @library{wxcore}
     @category{ctrl}
-    @appearance{gauge.png}
+    <!-- @appearance{gauge.png} -->
 
     @see wxSlider, wxScrollBar
 */
 class wxGauge : public wxControl
 {
 public:
-    //@{
+    /**
+        Default constructor.
+    */
+    wxGauge();
     /**
         Constructor, creating and showing a gauge.
 
@@ -54,27 +57,25 @@ public:
         @param id
             Window identifier.
         @param range
-            Integer range (maximum value) of the gauge. It is ignored when the gauge is
+            Integer range (maximum value) of the gauge. It is ignored when the
-        used in indeterminate mode.
+            gauge is used in indeterminate mode.
         @param pos
             Window position.
         @param size
             Window size.
         @param style
-            Gauge style. See wxGauge.
+            Gauge style.
         @param name
             Window name.
 
         @see Create()
     */
-    wxGauge();
     wxGauge(wxWindow* parent, wxWindowID id, int range,
             const wxPoint& pos = wxDefaultPosition,
             const wxSize& size = wxDefaultSize,
             long style = wxGA_HORIZONTAL,
             const wxValidator& validator = wxDefaultValidator,
             const wxString& name = "gauge");
-    //@}
 
     /**
         Destructor, destroying the gauge.
@@ -82,8 +83,8 @@ public:
     ~wxGauge();
 
     /**
-        Creates the gauge for two-step construction. See wxGauge()
+        Creates the gauge for two-step construction. See wxGauge() for further
-        for further details.
+        details.
     */
     bool Create(wxWindow* parent, wxWindowID id, int range,
                 const wxPoint& pos = wxDefaultPosition,
@@ -131,11 +132,12 @@ public:
     bool IsVertical() const;
 
     /**
-        Switch the gauge to indeterminate mode (if required) and makes the gauge move
+        Switch the gauge to indeterminate mode (if required) and makes the
-        a bit to indicate the user that some progress has been made.
+        gauge move a bit to indicate the user that some progress has been made.
-        Note that after calling this function the value returned by GetValue()
+
-        is undefined and thus you need to explicitely call SetValue() if you
+        @note After calling this function the value returned by GetValue() is
-        want to restore the determinate mode.
+              undefined and thus you need to explicitely call SetValue() if you
+              want to restore the determinate mode.
     */
     void Pulse();
 
@@ -150,8 +152,8 @@ public:
     void SetBezelFace(int width);
 
     /**
-        Sets the range (maximum value) of the gauge.
+        Sets the range (maximum value) of the gauge. This function makes the
-        This function makes the gauge switch to determinate mode, if it's not already.
+        gauge switch to determinate mode, if it's not already.
 
         @see GetRange()
     */
@@ -166,8 +168,9 @@ public:
     void SetShadowWidth(int width);
 
     /**
-        Sets the position of the gauge. The @a pos must be between 0 and the gauge
+        Sets the position of the gauge. The @a pos must be between 0 and the
-        range as returned by GetRange(), inclusive.
+        gauge range as returned by GetRange(), inclusive.
+
         This function makes the gauge switch to determinate mode, if it was in
         indeterminate mode before.
 

interface/gbsizer.h

@@ -10,23 +10,23 @@
     @class wxGBPosition
     @wxheader{gbsizer.h}
 
-    This class represents the position of an item in a virtual grid of
+    This class represents the position of an item in a virtual grid of rows and
-    rows and columns managed by a wxGridBagSizer.
+    columns managed by a wxGridBagSizer.
 
     @library{wxcore}
-    @category{FIXME}
+    @category{winlayout}
 */
 class wxGBPosition
 {
 public:
-    //@{
     /**
-        Construct a new wxGBPosition, optionally setting the row and column.
+        Default constructor, setting the row and column to (0,0).
-        The default is (0,0).
     */
     wxGBPosition();
+    /**
+        Construct a new wxGBPosition, setting the row and column.
+    */
     wxGBPosition(int row, int col);
-    //@}
 
     /**
         Get the current column value.
@@ -49,14 +49,14 @@ public:
     void SetRow(int row);
 
     /**
-        Is the wxGBPosition valid?  (An invalid wxGBPosition is (-1,-1). )
+        Checks if the position is valid. An invalid position is (-1,-1).
     */
     bool operator!(const wxGBPosition& p) const;
 
     /**
         Compare equality of two wxGBPositions.
     */
-    bool operator operator==(const wxGBPosition& p) const;
+    bool operator==(const wxGBPosition& p) const;
 };
 
 
@@ -65,11 +65,10 @@ public:
     @class wxGridBagSizer
     @wxheader{gbsizer.h}
 
-    A wxSizer that can lay out items in a virtual grid
+    A wxSizer that can lay out items in a virtual grid like a wxFlexGridSizer
-    like a wxFlexGridSizer but in this case
+    but in this case explicit positioning of the items is allowed using
-    explicit positioning of the items is allowed using
+    wxGBPosition, and items can optionally span more than one row and/or column
-    wxGBPosition, and items can optionally span
+    using wxGBSpan.
-    more than one row and/or column using wxGBSpan.
 
     @library{wxcore}
     @category{winlayout}
@@ -85,26 +84,20 @@ public:
 
     //@{
     /**
-        The Add methods return a valid pointer if the item was successfully placed at
+        Adds the given item to the given position.
-        the
+        
-        given position, @NULL if something was already there.
+        @returns A valid pointer if the item was successfully placed at the
+                 given position, or @NULL if something was already there.
     */
     wxSizerItem* Add(wxWindow* window, const wxGBPosition& pos,
                      const wxGBSpan& span = wxDefaultSpan,
-                     int flag = 0,
+                     int flag = 0, int border = 0, wxObject* userData = NULL);
-                     int border = 0,
-                     wxObject* userData = NULL);
     wxSizerItem* Add(wxSizer* sizer, const wxGBPosition& pos,
                      const wxGBSpan& span = wxDefaultSpan,
-                     int flag = 0,
+                     int flag = 0, int border = 0, wxObject* userData = NULL);
-                     int border = 0,
+    wxSizerItem* Add(int width, int height, const wxGBPosition& pos,
-                     wxObject* userData = NULL);
-    wxSizerItem* Add(int width, int height,
-                     const wxGBPosition& pos,
                      const wxGBSpan& span = wxDefaultSpan,
-                     int flag = 0,
+                     int flag = 0, int border = 0, wxObject* userData = NULL);
-                     int border = 0,
-                     wxObject* userData = NULL);
     wxSizerItem* Add(wxGBSizerItem* item);
     //@}
 
@@ -118,13 +111,12 @@ public:
     /**
         Look at all items and see if any intersect (or would overlap) the given
         item. Returns @true if so, @false if there would be no overlap. If an
-        excludeItem is given then it will not be checked for intersection, for
+        @a excludeItem is given then it will not be checked for intersection,
-        example it may be the item we are checking the position of.
+        for example it may be the item we are checking the position of.
     */
     bool CheckForIntersection(wxGBSizerItem* item,
                               wxGBSizerItem* excludeItem = NULL);
-    bool CheckForIntersection(const wxGBPosition& pos,
+    bool CheckForIntersection(const wxGBPosition& pos, const wxGBSpan& span,
-                              const wxGBSpan& span,
                               wxGBSizerItem* excludeItem = NULL);
     //@}
 
@@ -139,8 +131,8 @@ public:
 
     /**
         Return the sizer item located at the point given in pt, or @NULL if
-        there is no item at that point. The (x,y) coordinates in pt correspond
+        there is no item at that point. The (x,y) coordinates in @a pt
-        to the client coordinates of the window using the sizer for
+        correspond to the client coordinates of the window using the sizer for
         layout. (non-recursive)
     */
     wxGBSizerItem* FindItemAtPoint(const wxPoint& pt);
@@ -158,8 +150,8 @@ public:
     wxGBSizerItem* FindItemWithData(const wxObject* userData);
 
     /**
-        Get the size of the specified cell, including hgap and vgap. Only
+        Get the size of the specified cell, including hgap and vgap. Only valid
-        valid after a Layout.
+        after window layout has been performed.
     */
     wxSize GetCellSize(int row, int col) const;
 
@@ -179,7 +171,7 @@ public:
 
     //@{
     /**
-        Get the row/col spanning of the specified item
+        Get the row/col spanning of the specified item.
     */
     wxGBSpan GetItemSpan(wxWindow* window);
     wxGBSpan GetItemSpan(wxSizer* sizer);
@@ -226,40 +218,39 @@ public:
     @class wxGBSizerItem
     @wxheader{gbsizer.h}
 
-    The wxGBSizerItem class is used by the
+    The wxGBSizerItem class is used by the wxGridBagSizer for tracking the
-    wxGridBagSizer for tracking the items in the
+    items in the sizer. It adds grid position and spanning information to the
-    sizer. It adds grid position and spanning information to the normal
+    normal wxSizerItem by adding wxGBPosition and wxGBSpan attrbibutes. Most of
-    wxSizerItem by adding
+    the time you will not need to use a wxGBSizerItem directly in your code,
-    wxGBPosition and wxGBSpan
+    but there are a couple of cases where it is handy.
-    attrbibutes. Most of the time you will not need to use a
-    wxGBSizerItem directly in your code, but there are a couple of cases
-    where it is handy.
 
     @library{wxcore}
-    @category{FIXME}
+    @category{winlayout}
 */
 class wxGBSizerItem : public wxSizerItem
 {
 public:
-    //@{
+    /**
+        Construct a sizer item for tracking a spacer.
+    */
+    wxGBSizerItem(int width, int height, const wxGBPosition& pos,
+                  const wxGBSpan& span, int flag, int border,
+                  wxObject* userData);
+    /**
+        Construct a sizer item for tracking a window.
+    */
+    wxGBSizerItem(wxWindow* window, const wxGBPosition& pos,
+                  const wxGBSpan& span, int flag, int border,
+                  wxObject* userData);
     /**
         Construct a sizer item for tracking a subsizer.
     */
-    wxGBSizerItem(int width, int height, const wxGBPosition& pos,
-                  const wxGBSpan& span, int flag,
-                  int border, wxObject* userData);
-    wxGBSizerItem(wxWindow* window, const wxGBPosition& pos,
-                  const wxGBSpan& span,
-                  int flag, int border,
-                  wxObject* userData);
     wxGBSizerItem(wxSizer* sizer, const wxGBPosition& pos,
-                  const wxGBSpan& span,
+                  const wxGBSpan& span, int flag, int border,
-                  int flag, int border,
                   wxObject* userData);
-    //@}
 
     /**
-        Get the row and column of the endpoint of this item
+        Get the row and column of the endpoint of this item.
     */
     void GetEndPos(int& row, int& col);
 
@@ -268,7 +259,7 @@ public:
         Get the grid position of the item.
     */
     wxGBPosition GetPos() const;
-    const void GetPos(int& row, int& col) const;
+    void GetPos(int& row, int& col) const;
     //@}
 
     //@{
@@ -276,29 +267,29 @@ public:
         Get the row and column spanning of the item.
     */
     wxGBSpan GetSpan() const;
-    const void GetSpan(int& rowspan, int& colspan) const;
+    void GetSpan(int& rowspan, int& colspan) const;
     //@}
 
-    //@{
+    /**
+        Returns @true if this item and the @a other item instersect.
+    */
+    bool Intersects(const wxGBSizerItem& other);
     /**
         Returns @true if the given pos/span would intersect with this item.
     */
-    bool Intersects(const wxGBSizerItem& other);
+    bool Intersects(const wxGBPosition& pos, const wxGBSpan& span);
-    bool Intersects(const wxGBPosition& pos,
-                    const wxGBSpan& span);
-    //@}
 
     /**
-        If the item is already a member of a sizer then first ensure that
+        If the item is already a member of a sizer then first ensure that there
-        there is no other item that would intersect with this one at the new
+        is no other item that would intersect with this one at the new
         position, then set the new position. Returns @true if the change is
         successful and after the next Layout the item will be moved.
     */
     bool SetPos(const wxGBPosition& pos);
 
     /**
-        If the item is already a member of a sizer then first ensure that
+        If the item is already a member of a sizer then first ensure that there
-        there is no other item that would intersect with this one with its new
+        is no other item that would intersect with this one with its new
         spanning size, then set the new spanning. Returns @true if the change
         is successful and after the next Layout the item will be resized.
     */
@@ -311,24 +302,24 @@ public:
     @class wxGBSpan
     @wxheader{gbsizer.h}
 
-    This class is used to hold the row and column spanning attributes of
+    This class is used to hold the row and column spanning attributes of items
-    items in a wxGridBagSizer.
+    in a wxGridBagSizer.
 
     @library{wxcore}
-    @category{FIXME}
+    @category{winlayout}
 */
 class wxGBSpan
 {
 public:
-    //@{
     /**
-        Construct a new wxGBSpan, optionally setting the rowspan and colspan.
+        Default constructor, setting the rowspan and colspan to (1,1) meaning
-        The default is (1,1).  (Meaning that the item occupies one cell in
+        that the item occupies one cell in each direction.
-        each direction.
     */
     wxGBSpan();
+    /**
+        Construct a new wxGBSpan, setting the @a rowspan and @a colspan.
+    */
     wxGBSpan(int rowspan, int colspan);
-    //@}
 
     /**
         Get the current colspan value.
@@ -351,13 +342,13 @@ public:
     void SetRowspan(int rowspan);
 
     /**
-        Is the wxGBSpan valid?  (An invalid wxGBSpan is (-1,-1). )
+        Checks if the span is valid. An invalid span is (-1,-1).
     */
     bool operator!(const wxGBSpan& o) const;
 
     /**
         Compare equality of two wxGBSpans.
     */
-    bool operator operator==(const wxGBSpan& o) const;
+    bool operator==(const wxGBSpan& o) const;
 };
 

interface/gdicmn.h

@@ -8,9 +8,7 @@
 
 
 /**
-    Bitmap type flags.
+    Bitmap type flags. See wxBitmap and wxImage classes.
-
-    See wxBitmap and wxImage classes.
 */
 enum wxBitmapType
 {
@@ -51,47 +49,44 @@ enum wxBitmapType
 };
 
 /**
-    Standard cursors.
+    Standard cursors. See wxCursor.
-
-    See wxCursor.
 */
 enum wxStockCursor
 {
     wxCURSOR_NONE,
-    wxCURSOR_ARROW,
+    wxCURSOR_ARROW,             ///< A standard arrow cursor.
-    wxCURSOR_RIGHT_ARROW,
+    wxCURSOR_RIGHT_ARROW,       ///< A standard arrow cursor pointing to the right.
-    wxCURSOR_BULLSEYE,
+    wxCURSOR_BULLSEYE,          ///< Bullseye cursor.
-    wxCURSOR_CHAR,
+    wxCURSOR_CHAR,              ///< Rectangular character cursor.
-    wxCURSOR_CROSS,
+    wxCURSOR_CROSS,             ///< A cross cursor.
-    wxCURSOR_HAND,
+    wxCURSOR_HAND,              ///< A hand cursor.
-    wxCURSOR_IBEAM,
+    wxCURSOR_IBEAM,             ///< An I-beam cursor (vertical line).
-    wxCURSOR_LEFT_BUTTON,
+    wxCURSOR_LEFT_BUTTON,       ///< Represents a mouse with the left button depressed.
-    wxCURSOR_MAGNIFIER,
+    wxCURSOR_MAGNIFIER,         ///< A magnifier icon.
-    wxCURSOR_MIDDLE_BUTTON,
+    wxCURSOR_MIDDLE_BUTTON,     ///< Represents a mouse with the middle button depressed.
-    wxCURSOR_NO_ENTRY,
+    wxCURSOR_NO_ENTRY,          ///< A no-entry sign cursor.
-    wxCURSOR_PAINT_BRUSH,
+    wxCURSOR_PAINT_BRUSH,       ///< A paintbrush cursor.
-    wxCURSOR_PENCIL,
+    wxCURSOR_PENCIL,            ///< A pencil cursor.
-    wxCURSOR_POINT_LEFT,
+    wxCURSOR_POINT_LEFT,        ///< A cursor that points left.
-    wxCURSOR_POINT_RIGHT,
+    wxCURSOR_POINT_RIGHT,       ///< A cursor that points right.
-    wxCURSOR_QUESTION_ARROW,
+    wxCURSOR_QUESTION_ARROW,    ///< An arrow and question mark.
-    wxCURSOR_RIGHT_BUTTON,
+    wxCURSOR_RIGHT_BUTTON,      ///< Represents a mouse with the right button depressed.
-    wxCURSOR_SIZENESW,
+    wxCURSOR_SIZENESW,          ///< A sizing cursor pointing NE-SW.
-    wxCURSOR_SIZENS,
+    wxCURSOR_SIZENS,            ///< A sizing cursor pointing N-S.
-    wxCURSOR_SIZENWSE,
+    wxCURSOR_SIZENWSE,          ///< A sizing cursor pointing NW-SE.
-    wxCURSOR_SIZEWE,
+    wxCURSOR_SIZEWE,            ///< A sizing cursor pointing W-E.
-    wxCURSOR_SIZING,
+    wxCURSOR_SIZING,            ///< A general sizing cursor.
-    wxCURSOR_SPRAYCAN,
+    wxCURSOR_SPRAYCAN,          ///< A spraycan cursor.
-    wxCURSOR_WAIT,
+    wxCURSOR_WAIT,              ///< A wait cursor.
-    wxCURSOR_WATCH,
+    wxCURSOR_WATCH,             ///< A watch cursor.
-    wxCURSOR_BLANK,
+    wxCURSOR_BLANK,             ///< Transparent cursor.
-    wxCURSOR_DEFAULT,       //!< standard X11 cursor
+    wxCURSOR_DEFAULT,           ///< Standard X11 cursor (only in wxGTK).
-    wxCURSOR_COPY_ARROW ,   //!< MacOS Theme Plus arrow
+    wxCURSOR_COPY_ARROW ,       ///< MacOS Theme Plus arrow (only in wxMac).
-    // Not yet implemented for Windows
+    wxCURSOR_CROSS_REVERSE,     ///< Only available on wxX11.
-    wxCURSOR_CROSS_REVERSE,
+    wxCURSOR_DOUBLE_ARROW,      ///< Only available on wxX11.
-    wxCURSOR_DOUBLE_ARROW,
+    wxCURSOR_BASED_ARROW_UP,    ///< Only available on wxX11.
-    wxCURSOR_BASED_ARROW_UP,
+    wxCURSOR_BASED_ARROW_DOWN,  ///< Only available on wxX11.
-    wxCURSOR_BASED_ARROW_DOWN,
+    wxCURSOR_ARROWWAIT,         ///< A wait cursor with a standard arrow.
-    wxCURSOR_ARROWWAIT,
     wxCURSOR_MAX
 };
 
@@ -101,10 +96,10 @@ enum wxStockCursor
     @class wxRealPoint
     @wxheader{gdicmn.h}
 
-    A @b wxRealPoint is a useful data structure for graphics operations.
+    A wxRealPoint is a useful data structure for graphics operations.
 
-    It contains floating point @e x and @e y members.
+    It contains floating point @e x and @e y members. See wxPoint for an
-    See also wxPoint for an integer version.
+    integer version.
 
     @library{wxcore}
     @category{data}
@@ -148,51 +143,65 @@ public:
 class wxRect
 {
 public:
-    //@{
     /**
-        Creates a wxRect object from size values at the origin.
+        Default constructor.
     */
     wxRect();
+    /**
+        Creates a wxRect object from @a x, @a y, @a width and @a height values.
+    */
     wxRect(int x, int y, int width, int height);
+    /**
+        Creates a wxRect object from top-left and bottom-right points.
+    */
     wxRect(const wxPoint& topLeft, const wxPoint& bottomRight);
+    /**
+        Creates a wxRect object from position and @a size values.
+    */
     wxRect(const wxPoint& pos, const wxSize& size);
+    /**
+        Creates a wxRect object from @a size values at the origin.
+    */
     wxRect(const wxSize& size);
-    //@}
 
     //@{
     /**
-        Returns the rectangle having the same size as this one but centered relatively
+        Returns the rectangle having the same size as this one but centered
-        to the given rectangle @e r. By default, rectangle is centred in both
+        relatively to the given rectangle @a r. By default, rectangle is
-        directions but if @a dir includes only @c wxVERTICAL or only
+        centred in both directions but if @a dir includes only @c wxVERTICAL or
-        @c wxHORIZONTAL flag, then it is only centered in this direction while
+        only @c wxHORIZONTAL, then it is only centered in this direction while
         the other component of its position remains unchanged.
     */
     wxRect CentreIn(const wxRect& r, int dir = wxBOTH) const;
-    const wxRect  CenterIn(const wxRect& r, int dir = wxBOTH) const;
+    wxRect CenterIn(const wxRect& r, int dir = wxBOTH) const;
     //@}
 
-    //@{
     /**
-        Returns @true if the given rectangle is completely inside this rectangle
+        Returns @true if the given point is inside the rectangle (or on its
-        (or touches its boundary) and @false otherwise.
+        boundary) and @false otherwise.
     */
     bool Contains(int x, int y) const;
-    const bool Contains(const wxPoint& pt) const;
+    /**
-    const bool Contains(const wxRect& rect) const;
+        Returns @true if the given point is inside the rectangle (or on its
-    //@}
+        boundary) and @false otherwise.
+    */
+    bool Contains(const wxPoint& pt) const;
+    /**
+        Returns @true if the given rectangle is completely inside this
+        rectangle (or touches its boundary) and @false otherwise.
+    */
+    bool Contains(const wxRect& rect) const;
 
     //@{
     /**
         Decrease the rectangle size.
-        This method is the opposite from Inflate():
-        Deflate(a, b) is equivalent to Inflate(-a, -b).
-        Please refer to Inflate() for full description.
 
-        @see Inflate()
+        This method is the opposite from Inflate(): Deflate(a, b) is equivalent
+        to Inflate(-a, -b). Please refer to Inflate() for full description.
     */
-    void Deflate(wxCoord dx, wxCoord dy) const;
+    void Deflate(wxCoord dx, wxCoord dy);
-    void Deflate(const wxSize& diff) const;
+    void Deflate(const wxSize& diff);
-    void Deflate(wxCoord diff) const;
+    void Deflate(wxCoord diff);
     wxRect Deflate(wxCoord dx, wxCoord dy) const;
     //@}
 
@@ -217,7 +226,7 @@ public:
     int GetHeight() const;
 
     /**
-        Gets the left point of the rectangle (the same as wxRect::GetX).
+        Gets the left point of the rectangle (the same as GetX()).
     */
     int GetLeft() const;
 
@@ -239,7 +248,7 @@ public:
     wxSize GetSize() const;
 
     /**
-        Gets the top point of the rectangle (the same as wxRect::GetY).
+        Gets the top point of the rectangle (the same as GetY()).
     */
     int GetTop() const;
 
@@ -272,47 +281,45 @@ public:
     //@{
     /**
         Increases the size of the rectangle.
-        The second form uses the same @a diff for both @a dx and @e dy.
+
-        The first two versions modify the rectangle in place, the last one returns a
+        The left border is moved farther left and the right border is moved
-        new rectangle leaving this one unchanged.
+        farther right by @a dx. The upper border is moved farther up and the
-        The left border is moved farther left and the right border is moved farther
+        bottom border is moved farther down by @a dy. (Note the the width and
-        right by @e dx. The upper border is moved farther up and the bottom border
+        height of the rectangle thus change by 2*dx and 2*dy, respectively.) If
-        is moved farther down by @e dy. (Note the the width and height of the
+        one or both of @a dx and @a dy are negative, the opposite happens: the
-        rectangle thus change by 2*@a dx and 2*@e dy, respectively.) If one or
+        rectangle size decreases in the respective direction.
-        both of @a dx and @a dy are negative, the opposite happens: the rectangle
+
-        size decreases in the respective direction.
+        Inflating and deflating behaves "naturally". Defined more precisely,
-        Inflating and deflating behaves "naturally". Defined more precisely, that
+        that means:
-        means:
+        -# "Real" inflates (that is, @a dx and/or @a dy = 0) are not
-             "Real" inflates (that is, @a dx and/or @a dy = 0) are not
+           constrained. Thus inflating a rectangle can cause its upper left
-                constrained. Thus inflating a rectangle can cause its upper left corner
+           corner to move into the negative numbers. (2.5.4 and older forced
-                to move into the negative numbers. (the versions prior to 2.5.4 forced
+           the top left coordinate to not fall below (0, 0), which implied a
-                the top left coordinate to not fall below (0, 0), which implied a
+           forced move of the rectangle.)
-                forced move of the rectangle.)
+        -# Deflates are clamped to not reduce the width or height of the
-             Deflates are clamped to not reduce the width or height of the
+           rectangle below zero. In such cases, the top-left corner is
-                rectangle below zero. In such cases, the top-left corner is nonetheless
+           nonetheless handled properly. For example, a rectangle at (10, 10)
-                handled properly. For example, a rectangle at (10, 10) with size (20,
+           with size (20, 40) that is inflated by (-15, -15) will become
-                40) that is inflated by (-15, -15) will become located at (20, 25) at
+           located at (20, 25) at size (0, 10). Finally, observe that the width
-                size (0, 10). Finally, observe that the width and height are treated
+           and height are treated independently. In the above example, the
-                independently. In the above example, the width is reduced by 20,
+           width is reduced by 20, whereas the height is reduced by the full 30
-                whereas the height is reduced by the full 30 (rather than also stopping
+           (rather than also stopping at 20, when the width reached zero).
-                at 20, when the width reached zero).
 
         @see Deflate()
     */
-    void Inflate(wxCoord dx, wxCoord dy) const;
+    void Inflate(wxCoord dx, wxCoord dy);
-    void Inflate(const wxSize& diff) const;
+    void Inflate(const wxSize& diff);
-    void Inflate(wxCoord diff) const;
+    void Inflate(wxCoord diff);
     wxRect Inflate(wxCoord dx, wxCoord dy) const;
     //@}
 
     //@{
     /**
-        Modifies the rectangle to contain the overlapping box of this rectangle and the
+        Modifies the rectangle to contain the overlapping box of this rectangle
-        one passed in as parameter. The const version returns the new rectangle, the
+        and the one passed in as parameter.
-        other one modifies this rectangle in place.
     */
-    wxRect Intersect(const wxRect& rect);
+    wxRect Intersect(const wxRect& rect) const;
-    const wxRect&  Intersect(const wxRect& rect);
+    wxRect& Intersect(const wxRect& rect);
     //@}
 
     /**
@@ -322,8 +329,8 @@ public:
     bool Intersects(const wxRect& rect) const;
 
     /**
-        Returns @true if this rectangle has a width or height less than or equal to
+        Returns @true if this rectangle has a width or height less than or
-        0 and @false otherwise.
+        equal to 0 and @false otherwise.
     */
     bool IsEmpty() const;
 
@@ -366,30 +373,32 @@ public:
 
     //@{
     /**
-        Modifies the rectangle to contain the bounding box of this rectangle and the
+        Modifies the rectangle to contain the bounding box of this rectangle
-        one passed in as parameter. The const version returns the new rectangle, the
+        and the one passed in as parameter.
-        other one modifies this rectangle in place.
     */
-    wxRect Union(const wxRect& rect);
+    wxRect Union(const wxRect& rect) const;
-    const wxRect&  Union(const wxRect& rect);
+    wxRect& Union(const wxRect& rect);
     //@}
 
     /**
-        int height
+        Inequality operator.
-        Height member.
     */
+    bool operator !=(const wxRect& r1, const wxRect& r2);
 
+    //@{
+    /**
+        Like Union(), but doesn't treat empty rectangles specially.
+    */
+    wxRect operator +(const wxRect& r1, const wxRect& r2);
+    wxRect& operator +=(const wxRect& r);
+    //@}
 
     //@{
     /**
         Returns the intersection of two rectangles (which may be empty).
     */
-    bool operator !=(const wxRect& r1, const wxRect& r2);
+    wxRect operator *(const wxRect& r1, const wxRect& r2);
-    wxRect operator +(const wxRect& r1, const wxRect& r2);
+    wxRect& operator *=(const wxRect& r);
-    wxRect operator +=(const wxRect& r);
-    See also wxRect  operator *(const wxRect& r1,
-                                const wxRect& r2);
-    wxRect operator *=(const wxRect& r);
     //@}
 
     /**
@@ -403,21 +412,24 @@ public:
     bool operator ==(const wxRect& r1, const wxRect& r2);
 
     /**
-        int width
+        Height member.
+    */
+    int height;
+
+    /**
         Width member.
     */
-
+    int width;
 
     /**
-        int x
         x coordinate of the top-level corner of the rectangle.
     */
-
+    int x;
 
     /**
-        int y
         y coordinate of the top-level corner of the rectangle.
     */
+    int y;
 };
 
 
@@ -426,10 +438,10 @@ public:
     @class wxPoint
     @wxheader{gdicmn.h}
 
-    A @b wxPoint is a useful data structure for graphics operations.
+    A wxPoint is a useful data structure for graphics operations.
-    It simply contains integer @e x and @e y members.
 
-    See also wxRealPoint for a floating point version.
+    It contains integer @e x and @e y members. See wxRealPoint for a floating
+    point version.
 
     @library{wxcore}
     @category{data}
@@ -444,46 +456,47 @@ class wxPoint
 public:
     //@{
     /**
-        Create a point.
+        Constructs a point.
     */
     wxPoint();
     wxPoint(int x, int y);
     //@}
 
-    //@{
     /**
-        Operators for sum and subtraction between a wxPoint object and a
+        Assignment operator.
-        wxSize object.
     */
     void operator =(const wxPoint& pt);
+
     bool operator ==(const wxPoint& p1, const wxPoint& p2);
     bool operator !=(const wxPoint& p1, const wxPoint& p2);
+
     wxPoint operator +(const wxPoint& p1, const wxPoint& p2);
     wxPoint operator -(const wxPoint& p1, const wxPoint& p2);
-    wxPoint operator +=(const wxPoint& pt);
+
-    wxPoint operator -=(const wxPoint& pt);
+    wxPoint& operator +=(const wxPoint& pt);
+    wxPoint& operator -=(const wxPoint& pt);
+
     wxPoint operator +(const wxPoint& pt, const wxSize& sz);
     wxPoint operator -(const wxPoint& pt, const wxSize& sz);
     wxPoint operator +(const wxSize& sz, const wxPoint& pt);
     wxPoint operator -(const wxSize& sz, const wxPoint& pt);
-    wxPoint operator +=(const wxSize& sz);
+
-    wxPoint operator -=(const wxSize& sz);
+    wxPoint& operator +=(const wxSize& sz);
-    //@}
+    wxPoint& operator -=(const wxSize& sz);
 
     /**
-        int x
         x member.
     */
-
+    int x;
 
     /**
-        int  y
         y member.
     */
+    int  y;
 };
 
 /**
-    Global istance of a wxPoint initialized with values -1;-1.
+    Global istance of a wxPoint initialized with values (-1,-1).
 */
 wxPoint wxDefaultPosition;
 
@@ -493,17 +506,93 @@ wxPoint wxDefaultPosition;
     @wxheader{gdicmn.h}
 
     wxWidgets maintains a database of standard RGB colours for a predefined
-    set of named colours (such as "BLACK", "LIGHT GREY"). The
+    set of named colours. The application may add to this set if desired by
-    application may add to this set if desired by using
+    using AddColour() and may use it to look up colours by names using Find()
-    wxColourDatabase::AddColour and may use it to look up
+    or find the names for the standard colour using FindName().
-    colours by names using wxColourDatabase::Find or find the names
-    for the standard colour suing wxColourDatabase::FindName.
 
-    There is one predefined instance of this class called
+    There is one predefined, global instance of this class called
-    @b wxTheColourDatabase.
+    ::wxTheColourDatabase.
+
+    The standard database contains at least the following colours:
+
+    @beginTable
+    <tr><td>
+       AQUAMARINE
+    @n BLACK
+    @n BLUE
+    @n BLUE VIOLET
+    @n BROWN
+    @n CADET BLUE
+    @n CORAL
+    @n CORNFLOWER BLUE
+    @n CYAN
+    @n DARK GREY
+    @n DARK GREEN
+    @n DARK OLIVE GREEN
+    @n DARK ORCHID
+    @n DARK SLATE BLUE
+    @n DARK SLATE GREY
+    @n DARK TURQUOISE
+    @n DIM GREY
+    </td><td>
+       FIREBRICK
+    @n FOREST GREEN
+    @n GOLD
+    @n GOLDENROD
+    @n GREY
+    @n GREEN
+    @n GREEN YELLOW
+    @n INDIAN RED
+    @n KHAKI
+    @n LIGHT BLUE
+    @n LIGHT GREY
+    @n LIGHT STEEL BLUE
+    @n LIME GREEN
+    @n MAGENTA
+    @n MAROON
+    @n MEDIUM AQUAMARINE
+    @n MEDIUM BLUE
+    </td><td>
+       MEDIUM FOREST GREEN
+    @n MEDIUM GOLDENROD
+    @n MEDIUM ORCHID
+    @n MEDIUM SEA GREEN
+    @n MEDIUM SLATE BLUE
+    @n MEDIUM SPRING GREEN
+    @n MEDIUM TURQUOISE
+    @n MEDIUM VIOLET RED
+    @n MIDNIGHT BLUE
+    @n NAVY
+    @n ORANGE
+    @n ORANGE RED
+    @n ORCHID
+    @n PALE GREEN
+    @n PINK
+    @n PLUM
+    @n PURPLE
+    </td><td>
+       RED
+    @n SALMON
+    @n SEA GREEN
+    @n SIENNA
+    @n SKY BLUE
+    @n SLATE BLUE
+    @n SPRING GREEN
+    @n STEEL BLUE
+    @n TAN
+    @n THISTLE
+    @n TURQUOISE
+    @n VIOLET
+    @n VIOLET RED
+    @n WHEAT
+    @n WHITE
+    @n YELLOW
+    @n YELLOW GREEN
+    </td></tr>
+    @endTable
 
     @library{wxcore}
-    @category{FIXME}
+    @category{gdi}
 
     @see wxColour
 */
@@ -511,32 +600,27 @@ class wxColourDatabase
 {
 public:
     /**
-        Constructs the colour database. It will be initialized at the first use.
+        Constructs the colour database. It will be initialized at the first
+        use.
     */
     wxColourDatabase();
 
-    //@{
     /**
-        Adds a colour to the database. If a colour with the same name already exists,
+        Adds a colour to the database. If a colour with the same name already
-        it is replaced.
+        exists, it is replaced.
-        Please note that the overload taking a pointer is deprecated and will be
-        removed in the next wxWidgets version, please don't use it.
     */
-    void AddColour(const wxString& colourName,
+    void AddColour(const wxString& colourName, const wxColour& colour);
-                   const wxColour& colour);
-    void AddColour(const wxString& colourName, wxColour* colour);
-    //@}
 
     /**
-        Finds a colour given the name. Returns an invalid colour object (that is, such
+        Finds a colour given the name. Returns an invalid colour object (that
-        that its @ref wxColour::isok Ok method returns @false) if the colour wasn't
+        is, wxColour::IsOk() will return @false) if the colour wasn't found in
-        found in the database.
+        the database.
     */
     wxColour Find(const wxString& colourName);
 
     /**
-        Finds a colour name given the colour. Returns an empty string if the colour is
+        Finds a colour name given the colour. Returns an empty string if the
-        not found in the database.
+        colour is not found in the database.
     */
     wxString FindName(const wxColour& colour) const;
 };
@@ -546,16 +630,17 @@ public:
     @class wxSize
     @wxheader{gdicmn.h}
 
-    A @b wxSize is a useful data structure for graphics operations.
+    A wxSize is a useful data structure for graphics operations. It simply
-    It simply contains integer @e width and @e height members.
+    contains integer @e width and @e height members.
 
-    wxSize is used throughout wxWidgets as well as wxPoint which, although almost
+    wxSize is used throughout wxWidgets as well as wxPoint which, although
-    equivalent to wxSize, has a different meaning: wxPoint represents a position
+    almost equivalent to wxSize, has a different meaning: wxPoint represents a
-    while wxSize - the size.
+    position while wxSize represents the size.
 
-    @b wxPython note: wxPython defines aliases for the @c x and @c y members
+    @beginWxPythonOnly
-    named @c width and @c height since it makes much more sense for
+    wxPython defines aliases for the @e x and @e y members named @e width and
-    sizes.
+    @e height since it makes much more sense for sizes.
+    @endWxPythonOnly
 
     @library{wxcore}
     @category{data}
@@ -578,10 +663,7 @@ public:
 
     //@{
     /**
-        Decreases the size in x- and y- directions
+        Decreases the size in both x and y directions.
-             By @e size.x and @e size.y for the first overload
-             By @a dx and @a dy for the second one
-             By @a d and @a d for the third one
 
         @see IncBy()
     */
@@ -591,8 +673,8 @@ public:
     //@}
 
     /**
-        Decrements this object so that both of its dimensions are not greater than the
+        Decrements this object so that both of its dimensions are not greater
-        corresponding dimensions of the @e size.
+        than the corresponding dimensions of the @a size.
 
         @see IncTo()
     */
@@ -610,10 +692,7 @@ public:
 
     //@{
     /**
-        Increases the size in x- and y- directions
+        Increases the size in both x and y directions.
-             By @e size.x and @e size.y for the first overload
-             By @a dx and @a dy for the second one
-             By @a d and @a d for the third one
 
         @see DecBy()
     */
@@ -623,49 +702,31 @@ public:
     //@}
 
     /**
-        Increments this object so that both of its dimensions are not less than the
+        Increments this object so that both of its dimensions are not less than
-        corresponding dimensions of the @e size.
+        the corresponding dimensions of the @a size.
 
         @see DecTo()
     */
     void IncTo(const wxSize& size);
 
     /**
-        Returns @true if neither of the size object components is equal to -1, which
+        Returns @true if neither of the size object components is equal to -1,
-        is used as default for the size values in wxWidgets (hence the predefined
+        which is used as default for the size values in wxWidgets (hence the
-        @c wxDefaultSize has both of its components equal to -1).
+        predefined ::wxDefaultSize has both of its components equal to -1).
-        This method is typically used before calling
+
-        SetDefaults().
+        This method is typically used before calling SetDefaults().
     */
     bool IsFullySpecified() const;
 
-    //@{
     /**
-        Operators for division and multiplication between a wxSize object and an
+        Scales the dimensions of this object by the given factors. If you want
-        integer.
+        to scale both dimensions by the same factor you can also use
-    */
+        operator*=().
-    void operator =(const wxSize& sz);
-    bool operator ==(const wxSize& s1, const wxSize& s2);
-    bool operator !=(const wxSize& s1, const wxSize& s2);
-    wxSize operator +(const wxSize& s1, const wxSize& s2);
-    wxSize operator -(const wxSize& s1, const wxSize& s2);
-    wxSize operator +=(const wxSize& sz);
-    wxSize operator -=(const wxSize& sz);
-    wxSize operator /(const wxSize& sz, int factor);
-    wxSize operator *(const wxSize& sz, int factor);
-    wxSize operator *(int factor, const wxSize& sz);
-    wxSize operator /=(int factor);
-    wxSize operator *=(int factor);
-    //@}
 
-    /**
+        @returns A reference to this object (so that you can concatenate other
-        Scales the dimensions of this object by the given factors.
+                 operations in the same line).
-        If you want to scale both dimensions by the same factor you can also use
-        the @ref operators() "operator *="
-        Returns a reference to this object (so that you can concatenate other
-        operations in the same line).
     */
-    wxSize Scale(float xscale, float yscale);
+    wxSize& Scale(float xscale, float yscale);
 
     /**
         Sets the width and height members.
@@ -673,9 +734,16 @@ public:
     void Set(int width, int height);
 
     /**
-        Combine this size object with another one replacing the default (i.e. equal
+        Combine this size object with another one replacing the default (i.e.
-        to -1) components of this object with those of the other. It is typically
+        equal to -1) components of this object with those of the other. It is
-        used like this:
+        typically used like this:
+
+        @code
+        if ( !size.IsFullySpecified() )
+        {
+            size.SetDefaults(GetDefaultSize());
+        }
+        @endcode
 
         @see IsFullySpecified()
     */
@@ -690,10 +758,29 @@ public:
         Sets the width.
     */
     void SetWidth(int width);
+
+    /**
+        Assignment operator.
+    */
+    void operator =(const wxSize& sz);
+
+    bool operator ==(const wxSize& s1, const wxSize& s2);
+    bool operator !=(const wxSize& s1, const wxSize& s2);
+
+    wxSize operator +(const wxSize& s1, const wxSize& s2);
+    wxSize operator -(const wxSize& s1, const wxSize& s2);
+    wxSize& operator +=(const wxSize& sz);
+    wxSize& operator -=(const wxSize& sz);
+
+    wxSize operator /(const wxSize& sz, int factor);
+    wxSize operator *(const wxSize& sz, int factor);
+    wxSize operator *(int factor, const wxSize& sz);
+    wxSize& operator /=(int factor);
+    wxSize& operator *=(int factor);
 };
 
 /**
-    Global instance of a wxSize object initialized with values -1;-1.
+    Global instance of a wxSize object initialized to (-1,-1).
 */
 wxSize wxDefaultSize;