revisions contributed by Utensil Candel

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

interface/odcombo.h

@@ -11,14 +11,12 @@
     @wxheader{odcombo.h}
 
     wxOwnerDrawnComboBox is a combobox with owner-drawn list items.
-    In essence, it is a wxComboCtrl with
+    In essence, it is a wxComboCtrl with wxVListBox popup and wxControlWithItems
-    wxVListBox popup and wxControlWithItems
     interface.
 
     Implementing item drawing and measuring is similar to wxVListBox.
     Application needs to subclass wxOwnerDrawnComboBox and implement
-    wxOwnerDrawnComboBox::OnDrawItem, wxOwnerDrawnComboBox::OnMeasureItem
+    OnDrawItem(), OnMeasureItem() and OnMeasureItemWidth().
-    and wxOwnerDrawnComboBox::OnMeasureItemWidth.
 
     @beginStyleTable
     @style{wxODCB_DCLICK_CYCLES}:
@@ -27,16 +25,18 @@
     @style{wxODCB_STD_CONTROL_PAINT}:
            Control itself is not custom painted using OnDrawItem. Even if this
            style is not used, writable wxOwnerDrawnComboBox is never custom
-           painted unless SetCustomPaintWidth is called.
+           painted unless SetCustomPaintWidth() is called.
     @endStyleTable
 
     @beginEventTable{wxCommandEvent}
     @event{EVT_COMBOBOX(id, func)}:
            Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on
-           the list is selected. Note that calling GetValue returns the new
+           the list is selected. Note that calling GetValue() returns the new
            value of selection.
     @endEventTable
 
+    @see Events emitted by wxComboCtrl.
+
     @library{wxadv}
     @category{ctrl}
     @appearance{ownerdrawncombobox.png}
@@ -46,6 +46,11 @@
 class wxOwnerDrawnComboBox : public wxComboCtrl
 {
 public:
+
+    /**
+        Default constructor.
+    */
+    wxOwnerDrawnComboBox();
     //@{
     /**
         Constructor, creating and showing a owner-drawn combobox.
@@ -53,13 +58,13 @@ public:
         @param parent
             Parent window. Must not be @NULL.
         @param id
-            Window identifier. The value wxID_ANY indicates a default value.
+            Window identifier. The value @c wxID_ANY indicates a default value.
         @param value
             Initial selection string. An empty string indicates no selection.
         @param pos
             Window position.
         @param size
-            Window size. If wxDefaultSize is specified then the window is
+            Window size. If @c wxDefaultSize is specified then the window is
         sized
             appropriately.
         @param n
@@ -75,13 +80,12 @@ public:
 
         @see Create(), wxValidator
     */
-    wxOwnerDrawnComboBox();
     wxOwnerDrawnComboBox(wxWindow* parent, wxWindowID id,
                          const wxString& value = "",
                          const wxPoint& pos = wxDefaultPosition,
                          const wxSize& size = wxDefaultSize,
                          int n = 0,
-                         const wxString choices[] = NULL,
+                         const wxString[] choices = NULL,
                          long style = 0,
                          const wxValidator& validator = wxDefaultValidator,
                          const wxString& name = "comboBox");
@@ -102,10 +106,10 @@ public:
 
     //@{
     /**
-        Creates the combobox for two-step construction. Derived classes
+        Creates the combobox for two-step construction.
-        should call or replace this function. See
+        See wxOwnerDrawnComboBox() for further details.
-        wxOwnerDrawnComboBox()
+
-        for further details.
+        @remarks Derived classes should call or replace this function.
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxString& value = "",
@@ -137,19 +141,22 @@ public:
 
     /**
         This method is used to draw the items background and, maybe, a border around it.
+
         The base class version implements a reasonable default behaviour which consists
         in drawing the selected item with the standard background colour and drawing a
         border around the item if it is either selected or current.
 
-        @remarks flags has the same meaning as with OnDrawItem.
+        @remarks flags has the same meaning as with OnDrawItem().
     */
     void OnDrawBackground(wxDC& dc, const wxRect& rect, int item,
                           int flags) const;
 
     /**
         The derived class may implement this function to actually draw the item
-        with the given index on the provided DC. If function is not implemented,
+        with the given index on the provided DC.
-        the item text is simply drawn, as if the control was a normal combobox.
+
+        If function is not implemented, the item text is simply drawn, as if the control
+        was a normal combobox.
 
         @param dc
             The device context to use for drawing
@@ -160,6 +167,15 @@ public:
             The index of the item to be drawn
         @param flags
             Combines any of the following flag values:
+
+            @beginStyleTable
+            @style{wxODCB_PAINTING_CONTROL}:
+                   Combo control is being painted, instead of a list item.
+                   Argument item may be @c wxNOT_FOUND in this case.
+            @style{wxODCB_PAINTING_SELECTED}:
+                   An item with selection background is being painted.
+                   DC text colour should already be correct.
+            @endStyleTable
     */
     void OnDrawItem(wxDC& dc, const wxRect& rect, int item,
                     int flags) const;
@@ -167,6 +183,7 @@ public:
     /**
         The derived class may implement this method to return the height of the
         specified item (in pixels).
+
         The default implementation returns text height, as if this control was
         a normal combobox.
     */
@@ -176,6 +193,7 @@ public:
         The derived class may implement this method to return the width of the
         specified item (in pixels). If -1 is returned, then the item text width
         is used.
+
         The default implementation returns -1.
     */
     wxCoord OnMeasureItemWidth(size_t item) const;

interface/palette.h

@@ -27,17 +27,25 @@
     @category{gdi}
 
     @stdobjects
-    ::Objects:, ::wxNullPalette,
+    ::wxNullPalette
 
-    @see wxDC::SetPalette, wxBitmap
+    @see wxDC::SetPalette(), wxBitmap
 */
 class wxPalette : public wxGDIObject
 {
 public:
-    //@{
+
     /**
-        Creates a palette from arrays of size @e n, one for each
+        Default constructor.
-        red, blue or green component.
+    */
+    wxPalette();
+    /**
+        Copy constructor, uses @ref overview_refcount.
+    */
+    wxPalette(const wxPalette& palette);
+    /**
+        Creates a palette from arrays of size @e n, one for each red, blue or
+        green component.
 
         @param palette
             A pointer or reference to the palette to copy.
@@ -52,23 +60,20 @@ public:
 
         @see Create()
     */
-    wxPalette();
-    wxPalette(const wxPalette& palette);
     wxPalette(int n, const unsigned char* red,
               const unsigned char* green,
               const unsigned char* blue);
-    //@}
 
     /**
         Destructor.
-        See @ref overview_refcountdestruct "reference-counted object destruction" for
+
-        more info.
+        @see @ref overview_refcount_destruct "reference-counted object destruction"
     */
     ~wxPalette();
 
     /**
-        Creates a palette from arrays of size @e n, one for each
+        Creates a palette from arrays of size @e n, one for each red, blue or
-        red, blue or green component.
+        green component.
 
         @param n
             The number of indices in the palette.
@@ -102,7 +107,7 @@ public:
         @param blue
             Blue value.
 
-        @returns The nearest palette index or wxNOT_FOUND for unexpected errors.
+        @returns The nearest palette index or @c wxNOT_FOUND for unexpected errors.
 
         @see GetRGB()
     */
@@ -135,18 +140,12 @@ public:
     bool IsOk() const;
 
     /**
-        Assignment operator, using @ref overview_trefcount "reference counting".
+        Assignment operator, using @ref overview_refcount.
     */
-    wxPalette operator =(const wxPalette& palette);
+    wxPalette& operator =(const wxPalette& palette);
 };
 
 
-/**
-    FIXME
-*/
-wxPalette Objects:
-;
-
 /**
     FIXME
 */

interface/panel.h

@@ -18,11 +18,11 @@
 
     @e Note: Tab traversal is implemented through an otherwise undocumented
     intermediate wxControlContainer class from which any class can derive
-    in addition to the normal wxWindow base class. Please see wx/containr.h
+    in addition to the normal wxWindow base class. Please see @e wx/containr.h
-    and wx/panel.h to find out how this is achieved.
+    and @e wx/panel.h to find out how this is achieved.
 
     @e Note: if not all characters are being intercepted by your OnKeyDown or
-    OnChar handler, it may be because you are using the wxTAB_TRAVERSAL style,
+    OnChar handler, it may be because you are using the @c wxTAB_TRAVERSAL style,
     which grabs some keypresses for use by child controls.
 
     @library{wxbase}
@@ -33,20 +33,24 @@
 class wxPanel : public wxWindow
 {
 public:
-    //@{
+
+    /**
+        Default constructor.
+    */
+    wxPanel();
     /**
         Constructor.
 
         @param parent
             The parent window.
         @param id
-            An identifier for the panel. A value of -1 is taken to mean a default.
+            An identifier for the panel. @c wxID_ANY is taken to mean a default.
         @param pos
-            The panel position. The value wxDefaultPosition indicates a default position,
+            The panel position. The value @c wxDefaultPosition indicates a default position,
         chosen by
             either the windowing system or wxWidgets, depending on platform.
         @param size
-            The panel size. The value wxDefaultSize indicates a default size, chosen by
+            The panel size. The value @c wxDefaultSize indicates a default size, chosen by
             either the windowing system or wxWidgets, depending on platform.
         @param style
             The window style. See wxPanel.
@@ -57,13 +61,11 @@ public:
 
         @see Create()
     */
-    wxPanel();
     wxPanel(wxWindow* parent, wxWindowID id = wxID_ANY,
             const wxPoint& pos = wxDefaultPosition,
             const wxSize& size = wxDefaultSize,
             long style = wxTAB_TRAVERSAL,
             const wxString& name = "panel");
-    //@}
 
     /**
         Destructor. Deletes any child windows before deleting the physical window.
@@ -71,7 +73,7 @@ public:
     ~wxPanel();
 
     /**
-        This method is overridden from wxWindow::AcceptsFocus
+        This method is overridden from wxWindow::AcceptsFocus()
         and returns @true only if there is no child window in the panel which
         can accept the focus. This is reevaluated each time a child
         window is added or removed from the panel.
@@ -79,8 +81,7 @@ public:
     bool AcceptsFocus() const;
 
     /**
-        Used for two-step panel construction. See wxPanel()
+        Used for two-step panel construction. See wxPanel() for details.
-        for details.
     */
     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
                 const wxPoint& pos = wxDefaultPosition,
@@ -89,8 +90,8 @@ public:
                 const wxString& name = "panel");
 
     /**
-        Sends a wxInitDialogEvent, which
+        Sends a wxInitDialogEvent, which in turn transfers data to the dialog via
-        in turn transfers data to the dialog via validators.
+        validators.
 
         @see wxInitDialogEvent
     */
@@ -106,7 +107,7 @@ public:
                  (Windows only). Add an event table entry for your panel
                  class if you wish the behaviour to be different (such
                  as keeping a user-defined background colour). If you do
-                 override this function, call wxEvent::Skip to propagate
+                 override this function, call wxEvent::Skip() to propagate
                  the notification to child windows and controls.
 
         @see wxSysColourChangedEvent
@@ -114,13 +115,13 @@ public:
     void OnSysColourChanged(wxSysColourChangedEvent& event);
 
     /**
-        Overrides wxWindow::SetFocus. This method
+        Overrides wxWindow::SetFocus(). This method
         uses the (undocumented) mix-in class wxControlContainer which manages
         the focus and TAB logic for controls which usually have child controls.
         In practice, if you call this method and the control has at least
         one child window, the focus will be given to the child window.
 
-        @see wxFocusEvent, wxWindow::SetFocus
+        @see wxFocusEvent, wxWindow::SetFocus()
     */
     virtual void SetFocus();
 

interface/pen.h

@@ -104,22 +104,24 @@ enum wxPenCap
     lines and painting the outline of rectangles, ellipses, etc.
     It has a colour, a width and a style.
 
+    @remarks
+
     On a monochrome display, wxWidgets shows all non-white pens as black.
 
     Do not initialize objects on the stack before the program commences,
     since other required structures may not have been set up yet.
-    Instead, define global pointers to objects and create them in wxApp::OnInit
+    Instead, define global pointers to objects and create them in wxApp::OnInit()
     or when required.
 
     An application may wish to dynamically create pens with different characteristics,
     and there is the consequent danger that a large number of duplicate pens will
     be created. Therefore an application may wish to get a pointer to a pen by using
-    the global list of pens wxThePenList, and calling the member function
+    the global list of pens ::wxThePenList, and calling the member function
     wxPenList::FindOrCreatePen().
     See the entry for wxPenList.
 
-    This class uses reference counting and copy-on-write internally so that
+    This class uses @ref overview_refcount "reference counting and copy-on-write" internally
-    assignments between two instances of this class are very cheap.
+    so that assignments between two instances of this class are very cheap.
     You can therefore use actual objects instead of pointers without efficiency problems.
     If an instance of this class is changed it will create its own data internally
     so that other instances, which previously shared the data using the reference
@@ -129,44 +131,30 @@ enum wxPenCap
     @category{gdi}
 
     @stdobjects
-    ::wxNullPen, ::wxRED_PEN, ::wxCYAN_PEN, ::wxGREEN_PEN, ::wxBLACK_PEN,
+    ::wxNullPen
-    ::wxWHITE_PEN, ::wxTRANSPARENT_PEN, ::wxBLACK_DASHED_PEN, ::wxGREY_PEN,
-    ::wxMEDIUM_GREY_PEN, ::wxLIGHT_GREY_PEN
 
-    @see wxPenList, wxDC, wxDC::SetPen
+    <b>Predefined pointers:</b> ::wxRED_PEN, ::wxCYAN_PEN, ::wxGREEN_PEN,
+    ::wxBLACK_PEN, ::wxWHITE_PEN, ::wxTRANSPARENT_PEN, ::wxBLACK_DASHED_PEN,
+    ::wxGREY_PEN, ::wxMEDIUM_GREY_PEN, ::wxLIGHT_GREY_PEN
+
+    @see wxPenList, wxDC, wxDC::SetPen()
 */
 class wxPen : public wxGDIObject
 {
 public:
     /**
-        Default constructor. The pen will be uninitialised, and wxPen:IsOk will return @false.
+        Default constructor. The pen will be uninitialised, and IsOk() will return @false.
     */
     wxPen();
 
     /**
         Constructs a pen from a colour object, pen width and style.
-    */
-    wxPen(const wxColour& colour, int width = 1, wxPenStyle style = wxPENSTYLE_SOLID);
-
-    /**
-        Constructs a stippled pen from a stipple bitmap and a width.
-    */
-    wxPen(const wxBitmap& stipple, int width);
-
-    /**
-        Copy constructor, uses @ref overview_refcount "reference counting".
 
         @param colour
             A colour object.
-        @param colourName
-            A colour name.
         @param width
             Pen width. Under Windows, the pen width cannot be greater than 1 if
-            the style is wxDOT, wxLONG_DASH, wxSHORT_DASH, wxDOT_DASH, or wxUSER_DASH.
+            the style is @c wxDOT, @c wxLONG_DASH, @c wxSHORT_DASH, @c wxDOT_DASH, or @c wxUSER_DASH.
-        @param stipple
-            A stipple bitmap.
-        @param pen
-            A pointer or reference to a pen to copy.
         @param style
             The style may be one of the ::wxPenStyle values.
 
@@ -175,14 +163,34 @@ public:
                  above - there is no similarity even between Windows95
                  and Windows98 - so handle with care.
 
-        @see SetStyle(), SetColour(), SetWidth(), SetStipple()
+        @see SetStyle(), SetColour(), SetWidth()
+    */
+    wxPen(const wxColour& colour, int width = 1, wxPenStyle style = wxPENSTYLE_SOLID);
+
+    /**
+        Constructs a stippled pen from a stipple bitmap and a width.
+
+        @param width
+            Pen width. Under Windows, the pen width cannot be greater than 1 if
+            the style is @c wxDOT, @c wxLONG_DASH, @c wxSHORT_DASH, @c wxDOT_DASH, or @c wxUSER_DASH.
+        @param stipple
+            A stipple bitmap.
+
+        @see SetWidth(), SetStipple()
+    */
+    wxPen(const wxBitmap& stipple, int width);
+
+    /**
+        Copy constructor, uses @ref overview_refcount.
+
+        @param pen
+            A pointer or reference to a pen to copy.
     */
     wxPen(const wxPen& pen);
 
     /**
         Destructor.
-        See @ref overview_refcountdestruct "reference-counted object destruction" for
+        @see @ref overview_refcount_destruct "reference-counted object destruction"
-        more info.
 
         @remarks Although all remaining pens are deleted when the application
                  exits, the application should try to clean up all pens
@@ -193,9 +201,10 @@ public:
     ~wxPen();
 
     /**
-        Returns the pen cap style, which may be one of @b wxCAP_ROUND, @b
+        Returns the pen cap style, which may be one of @c wxCAP_ROUND, @c
-        wxCAP_PROJECTING and
+        wxCAP_PROJECTING and @c wxCAP_BUTT.
-        @b wxCAP_BUTT. The default is @b wxCAP_ROUND.
+
+        The default is @c wxCAP_ROUND.
 
         @see SetCap()
     */
@@ -212,16 +221,18 @@ public:
         Gets an array of dashes (defined as char in X, DWORD under Windows).
         @a dashes is a pointer to the internal array. Do not deallocate or store this
         pointer.
-        The function returns the number of dashes associated with this pen.
+
+        @return The number of dashes associated with this pen.
 
         @see SetDashes()
     */
     virtual int GetDashes(wxDash** dashes) const;
 
     /**
-        Returns the pen join style, which may be one of @b wxJOIN_BEVEL, @b
+        Returns the pen join style, which may be one of @c wxJOIN_BEVEL, @c
-        wxJOIN_ROUND and
+        wxJOIN_ROUND and @c wxJOIN_MITER.
-        @b wxJOIN_MITER. The default is @b wxJOIN_ROUND.
+
+        The default is @c wxJOIN_ROUND.
 
         @see SetJoin()
     */
@@ -254,9 +265,8 @@ public:
     bool IsOk() const;
 
     /**
-        Sets the pen cap style, which may be one of @b wxCAP_ROUND, @b wxCAP_PROJECTING
+        Sets the pen cap style, which may be one of @c wxCAP_ROUND, @c wxCAP_PROJECTING
-        and
+        and @c wxCAP_BUTT. The default is @c wxCAP_ROUND.
-        @b wxCAP_BUTT. The default is @b wxCAP_ROUND.
 
         @see GetCap()
     */
@@ -274,19 +284,21 @@ public:
 
     /**
         Associates an array of pointers to dashes (defined as char in X, DWORD under
-        Windows)
+        Windows) with the pen.
-        with the pen. The array is not deallocated by wxPen, but neither must it be
+
-        deallocated by the calling application until the pen is deleted or this
+        The array is not deallocated by wxPen, but neither must it be deallocated by
-        function is called with a @NULL array.
+        the calling application until the pen is deleted or this function is called
+        with a @NULL array.
 
         @see GetDashes()
     */
     virtual void SetDashes(int n, wxDash* dashes);
 
     /**
-        Sets the pen join style, which may be one of @b wxJOIN_BEVEL, @b wxJOIN_ROUND
+        Sets the pen join style, which may be one of @c wxJOIN_BEVEL, @c wxJOIN_ROUND
-        and
+        and @c wxJOIN_MITER.
-        @b wxJOIN_MITER. The default is @b wxJOIN_ROUND.
+
+        The default is @c wxJOIN_ROUND.
 
         @see GetJoin()
     */
@@ -315,19 +327,19 @@ public:
 
     /**
         Inequality operator.
-        See @ref overview_refcountequality "reference-counted object comparison" for
+        See @ref overview_refcount_equality "reference-counted object comparison" for
         more info.
     */
     bool operator !=(const wxPen& pen);
 
     /**
-        Assignment operator, using @ref overview_trefcount "reference counting".
+        Assignment operator, using @ref overview_refcount.
     */
     wxPen operator =(const wxPen& pen);
 
     /**
         Equality operator.
-        See @ref overview_refcountequality "reference-counted object comparison" for
+        See @ref overview_refcount_equality "reference-counted object comparison" for
         more info.
     */
     bool operator ==(const wxPen& pen);

interface/pickerbase.h

@@ -11,13 +11,13 @@
     @wxheader{pickerbase.h}
 
     Base abstract class for all pickers which support an auxiliary text control.
+
     This class handles all positioning and sizing of the text control like a
-    an horizontal wxBoxSizer would do, with the text control on
+    an horizontal wxBoxSizer would do, with the text control on the left of the
-    the left of the picker button.
+    picker button.
-    The proportion (see wxSizer documentation for more info about
+    The proportion (see wxSizer documentation for more info about proportion values)
-    proportion values) of the picker control defaults to 1 when there isn't a text
+    of the picker control defaults to 1 when there isn't a text control associated
-    control
+    (see @c wxPB_USE_TEXTCTRL style) and to 0 otherwise.
-    associated (see @c wxPB_USE_TEXTCTRL style) and to 0 otherwise.
 
     @beginStyleTable
     @style{wxPB_USE_TEXTCTRL}:
@@ -26,7 +26,7 @@
     @endStyleTable
 
     @library{wxcore}
-    @category{FIXME}
+    @category{pickers}
 
     @see wxColourPickerCtrl
 */
@@ -35,6 +35,7 @@ class wxPickerBase : public wxControl
 public:
     /**
         Returns the margin (in pixel) between the picker and the text control.
+
         This function can be used only when HasTextCtrl() returns @true.
     */
     int GetInternalMargin() const;
@@ -46,22 +47,28 @@ public:
 
     /**
         Returns a pointer to the text control handled by this window or @NULL if the
-        @b wxPB_USE_TEXTCTRL style was not specified when this control was created.
+        @c wxPB_USE_TEXTCTRL style was not specified when this control was created.
-        Very important: the contents of the text control could be containing an invalid
+
-        representation of the entity which can be chosen through the picker (e.g. the user entered an invalid colour syntax because of a typo). Thus you should never parse the content of the textctrl to get the user's input; rather use the derived-class getter (e.g. wxColourPickerCtrl::GetColour, wxFilePickerCtrl::GetPath, etc).
+        @remarks
+        The contents of the text control could be containing an invalid
+        representation of the entity which can be chosen through the picker
+        (e.g. the user entered an invalid colour syntax because of a typo).
+        Thus you should never parse the content of the textctrl to get the
+        user's input; rather use the derived-class getter
+        (e.g. wxColourPickerCtrl::GetColour(), wxFilePickerCtrl::GetPath(), etc).
     */
     wxTextCtrl* GetTextCtrl();
 
     /**
         Returns the proportion value of the text control.
+
         This function can be used only when HasTextCtrl() returns @true.
     */
     int GetTextCtrlProportion() const;
 
     /**
-        Returns @true if this window has a valid text control (i.e. if the @b
+        Returns @true if this window has a valid text control (i.e. if the @c
-        wxPB_USE_TEXTCTRL style was
+        wxPB_USE_TEXTCTRL style was given when creating this control).
-        given when creating this control).
     */
     bool HasTextCtrl() const;
 
@@ -72,12 +79,14 @@ public:
 
     /**
         Returns @true if the text control is growable.
+
         This function can be used only when HasTextCtrl() returns @true.
     */
     bool IsTextCtrlGrowable() const;
 
     /**
         Sets the margin (in pixel) between the picker and the text control.
+
         This function can be used only when HasTextCtrl() returns @true.
     */
     void SetInternalMargin(int margin);
@@ -89,18 +98,21 @@ public:
 
     /**
         Sets the proportion value of the picker.
+
         Look at the overview of wxPickerBase for more details about this.
     */
     void SetPickerCtrlProportion(int prop);
 
     /**
         Sets the text control as growable when @c grow is @true.
+
         This function can be used only when HasTextCtrl() returns @true.
     */
     void SetTextCtrlGrowable(bool grow = true);
 
     /**
         Sets the proportion value of the text control.
+
         Look at the overview of wxPickerBase for more details about this.
         This function can be used only when HasTextCtrl() returns @true.
     */

interface/platinfo.h

@@ -11,24 +11,146 @@
     @wxheader{platinfo.h}
 
     This class holds informations about the operating system and the toolkit that
-    the application
+    the application is running under and some basic architecture info of the machine
-    is running under and some basic architecture info of the machine where it's
+    where it's running.
-    running.
 
     @library{wxbase}
-    @category{FIXME}
+    @category{misc}
 
-    @see wxGetOSVersion(), wxIsPlatformLittleEndian(), wxIsPlatform64Bit(),
+    @see ::wxGetOsVersion(), wxIsPlatformLittleEndian(), wxIsPlatform64Bit(),
     wxAppTraits
+
+    <b>Data structures:</b>
+
+    The following are the operating systems which are recognized by wxWidgets and
+    whose version can be detected at run-time.
+    The values of the constants are chosen so that they can be combined as flags;
+    this allows to check for operating system families like
+    e.g. wxOS_MAC and wxOS_UNIX.
+
+    @code
+
+    enum wxOperatingSystemId
+    {
+        wxOS_UNKNOWN = 0,                 // returned on error
+
+        wxOS_MAC_OS         = 1 << 0,     // Apple Mac OS 8/9/X with Mac paths
+        wxOS_MAC_OSX_DARWIN = 1 << 1,     // Apple Mac OS X with Unix paths
+        wxOS_MAC = wxOS_MAC_OS|wxOS_MAC_OSX_DARWIN,
+
+        wxOS_WINDOWS_9X     = 1 << 2,     // Windows 9x family (95/98/ME)
+        wxOS_WINDOWS_NT     = 1 << 3,     // Windows NT family (NT/2000/XP)
+        wxOS_WINDOWS_MICRO  = 1 << 4,     // MicroWindows
+        wxOS_WINDOWS_CE     = 1 << 5,     // Windows CE (Window Mobile)
+        wxOS_WINDOWS = wxOS_WINDOWS_9X      |
+                       wxOS_WINDOWS_NT      |
+                       wxOS_WINDOWS_MICRO   |
+                       wxOS_WINDOWS_CE,
+
+        wxOS_UNIX_LINUX     = 1 << 6,       // Linux
+        wxOS_UNIX_FREEBSD   = 1 << 7,       // FreeBSD
+        wxOS_UNIX_OPENBSD   = 1 << 8,       // OpenBSD
+        wxOS_UNIX_NETBSD    = 1 << 9,       // NetBSD
+        wxOS_UNIX_SOLARIS   = 1 << 10,      // SunOS
+        wxOS_UNIX_AIX       = 1 << 11,      // AIX
+        wxOS_UNIX_HPUX      = 1 << 12,      // HP/UX
+        wxOS_UNIX = wxOS_UNIX_LINUX     |
+                    wxOS_UNIX_FREEBSD   |
+                    wxOS_UNIX_OPENBSD   |
+                    wxOS_UNIX_NETBSD    |
+                    wxOS_UNIX_SOLARIS   |
+                    wxOS_UNIX_AIX       |
+                    wxOS_UNIX_HPUX,
+
+        wxOS_DOS            = 1 << 15,      // Microsoft DOS
+        wxOS_OS2            = 1 << 16       // OS/2
+    };
+
+    @endcode
+
+    The list of wxWidgets ports.
+    Some of them can be used with more than a single (native) toolkit;
+    e.g. wxWinCE port sources can be used with smartphones, pocket PCs
+    and handheld devices SDKs.
+
+    @code
+
+    enum wxPortId
+    {
+        wxPORT_UNKNOWN  = 0,            // returned on error
+
+        wxPORT_BASE     = 1 << 0,       // wxBase, no native toolkit used
+
+        wxPORT_MSW      = 1 << 1,       // wxMSW, native toolkit is Windows API
+        wxPORT_MOTIF    = 1 << 2,       // wxMotif, using [Open]Motif or Lesstif
+        wxPORT_GTK      = 1 << 3,       // wxGTK, using GTK+ 1.x, 2.x, GPE or Maemo
+        wxPORT_MGL      = 1 << 4,       // wxMGL, using wxUniversal
+        wxPORT_X11      = 1 << 5,       // wxX11, using wxUniversal
+        wxPORT_OS2      = 1 << 6,       // wxOS2, using OS/2 Presentation Manager
+        wxPORT_MAC      = 1 << 7,       // wxMac, using Carbon or Classic Mac API
+        wxPORT_COCOA    = 1 << 8,       // wxCocoa, using Cocoa NextStep/Mac API
+        wxPORT_WINCE    = 1 << 9,       // wxWinCE, toolkit is WinCE SDK API
+        wxPORT_PALMOS   = 1 << 10,      // wxPalmOS, toolkit is PalmOS API
+        wxPORT_DFB      = 1 << 11       // wxDFB, using wxUniversal
+    };
+
+    @endcode
+
+    The architecture of the operating system
+    (regardless of the build environment of wxWidgets library
+    - see wxIsPlatform64bit documentation for more info).
+
+    @code
+
+    enum wxArchitecture
+    {
+        wxARCH_INVALID = -1,        // returned on error
+
+        wxARCH_32,                  // 32 bit
+        wxARCH_64,
+
+        wxARCH_MAX
+    }
+
+    @endcode
+
+    The endian-ness of the machine.
+
+    @code
+
+    enum wxEndianness
+    {
+        wxENDIAN_INVALID = -1,      // returned on error
+
+        wxENDIAN_BIG,               // 4321
+        wxENDIAN_LITTLE,            // 1234
+        wxENDIAN_PDP,               // 3412
+
+        wxENDIAN_MAX
+    }
+
+    @endcode
+
+
 */
 class wxPlatformInfo : public wxObject
 {
 public:
-    //@{
+
+    /**
+        Initializes the instance with the values corresponding to the currently
+        running platform.
+
+        This is a fast operation because it only requires to copy the values
+        internally cached for the currently running platform.
+
+        @see Get()
+    */
+    wxPlatformInfo();
+
     /**
         Initializes the object using given values.
     */
-    wxPlatformInfo();
     wxPlatformInfo(wxPortId pid = wxPORT_UNKNOWN,
                    int tkMajor = -1,
                    int tkMinor = -1,
@@ -37,7 +159,7 @@ public:
                    int osMinor = -1,
                    wxArchitecture arch = wxARCH_INVALID,
                    wxEndianness endian = wxENDIAN_INVALID);
-    //@}
+
 
     /**
         Returns @true if the OS version is at least @c major.minor.
@@ -56,124 +178,162 @@ public:
     bool CheckToolkitVersion(int major, int minor) const;
 
     /**
-        Returns the global wxPlatformInfo object, initialized with the values for the
+        Returns the global wxPlatformInfo object, initialized with the values
-        currently running platform.
+        for the currently running platform.
     */
     static const wxPlatformInfo Get();
 
     /**
         Converts the given string to a wxArchitecture enum value or to
-        wxARCH_INVALID if the given string is not a valid architecture string
+        @c wxARCH_INVALID if the given string is not a valid architecture string
         (i.e. does not contain nor @c 32 nor @c 64 strings).
     */
     static wxArchitecture GetArch(const wxString& arch);
 
-    //@{
+    /**
+        Returns the name for the given wxArchitecture enumeration value.
+    */
+    static wxString GetArchName(wxArchitecture arch) const;
+
     /**
         Returns the name for the architecture of this wxPlatformInfo instance.
     */
-    static wxString GetArchName(wxArchitecture arch) const;
     wxString GetArchName() const;
-    //@}
 
     /**
         Returns the architecture ID of this wxPlatformInfo instance.
     */
     wxArchitecture GetArchitecture() const;
 
-    //@{
+    /**
+        Converts the given string to a wxEndianness enum value or to
+        @c wxENDIAN_INVALID if the given string is not a valid endianness
+        string (i.e. does not contain nor little nor big strings).
+    */
+    static wxEndianness GetEndianness(const wxString& end) const;
+
     /**
         Returns the endianness ID of this wxPlatformInfo instance.
     */
-    static wxEndianness GetEndianness(const wxString& end) const;
     wxEndianness GetEndianness() const;
-    //@}
 
-    //@{
+    /**
+        Returns name for the given wxEndianness enumeration value.
+    */
+    static wxString GetEndiannessName(wxEndianness end) const;
+
     /**
         Returns the name for the endianness of this wxPlatformInfo instance.
     */
-    static wxString GetEndiannessName(wxEndianness end) const;
     wxString GetEndiannessName() const;
-    //@}
 
     /**
         Returns the run-time major version of the OS associated with this
         wxPlatformInfo instance.
-        See wxGetOsVersion() for more info.
 
-        @see CheckOSVersion()
+        @see ::wxGetOsVersion(), CheckOSVersion()
     */
     int GetOSMajorVersion() const;
 
     /**
         Returns the run-time minor version of the OS associated with this
         wxPlatformInfo instance.
-        See wxGetOsVersion() for more info.
 
-        @see CheckOSVersion()
+        @see ::wxGetOsVersion(), CheckOSVersion()
     */
     int GetOSMinorVersion() const;
 
-    //@{
+    /**
+        Returns the operating system family name for the given wxOperatingSystemId
+        enumeration value: @c Unix for @c wxOS_UNIX, @c Macintosh for @c wxOS_MAC,
+        @c Windows for @c wxOS_WINDOWS, @c DOS for @c wxOS_DOS, @c OS/2 for @c wxOS_OS2.
+    */
+    static wxString GetOperatingSystemFamilyName(wxOperatingSystemId os) const;
+
     /**
         Returns the operating system family name of the OS associated with this
         wxPlatformInfo instance.
     */
-    static wxString GetOperatingSystemFamilyName(wxOperatingSystemId os) const;
     wxString GetOperatingSystemFamilyName() const;
-    //@}
 
-    //@{
+    /**
+        Converts the given string to a wxOperatingSystemId enum value or to @c
+        wxOS_UNKNOWN if the given string is not a valid operating system name.
+    */
+    static wxOperatingSystemId GetOperatingSystemId(const wxString& name) const;
+
     /**
         Returns the operating system ID of this wxPlatformInfo instance.
     */
-    static wxOperatingSystemId GetOperatingSystemId(const wxString& name) const;
     wxOperatingSystemId GetOperatingSystemId() const;
-    //@}
 
-    //@{
+    /**
+        Returns the name for the given operating system ID value.
+
+        This can be a long name (e.g. <tt>Microsoft Windows NT</tt>);
+        use GetOperatingSystemFamilyName() to retrieve a short, generic name.
+    */
+    static wxString GetOperatingSystemIdName(wxOperatingSystemId os) const;
+
     /**
         Returns the operating system name of the OS associated with this wxPlatformInfo
         instance.
     */
-    static wxString GetOperatingSystemIdName(wxOperatingSystemId os) const;
     wxString GetOperatingSystemIdName() const;
-    //@}
 
-    //@{
+
+    /**
+        Converts the given string to a wxWidgets port ID value or to @c wxPORT_UNKNOWN
+        if the given string does not match any of the wxWidgets canonical name ports
+        ("wxGTK", "wxMSW", etc) nor any of the short wxWidgets name ports ("gtk", "msw", etc).
+    */
+    static wxPortId GetPortId(const wxString& portname) const;
+
     /**
         Returns the wxWidgets port ID associated with this wxPlatformInfo instance.
     */
-    static wxPortId GetPortId(const wxString& portname) const;
     wxPortId GetPortId() const;
-    //@}
 
-    //@{
+    /**
+        Returns the name of the given wxWidgets port ID value.
+        The @a usingUniversal argument specifies whether the port is in its native
+        or wxUniversal variant.
+
+        The returned string always starts with the "wx" prefix and is a mixed-case string.
+    */
+    static wxString GetPortIdName(wxPortId port, bool usingUniversal) const;
+
     /**
         Returns the name of the wxWidgets port ID associated with this wxPlatformInfo
         instance.
     */
-    static wxString GetPortIdName(wxPortId port, bool usingUniversal) const;
     wxString GetPortIdName() const;
-    //@}
 
-    //@{
+    /**
+        Returns the short name of the given wxWidgets port ID value.
+        The @a usingUniversal argument specifies whether the port is in its native
+        or wxUniversal variant.
+
+        The returned string does not start with the "wx" prefix and is always lower
+        case.
+    */
+    static wxString GetPortIdShortName(wxPortId port,
+                                       bool usingUniversal) const;
+
     /**
         Returns the short name of the wxWidgets port ID associated with this
         wxPlatformInfo instance.
     */
-    static wxString GetPortIdShortName(wxPortId port,
-                                       bool usingUniversal) const;
     wxString GetPortIdShortName() const;
-    //@}
 
     /**
         Returns the run-time major version of the toolkit associated with this
         wxPlatformInfo instance.
-        Note that if GetPortId() returns wxPORT_BASE, then this value is zero (unless
+
-        externally modified with wxPlatformInfo::SetToolkitVersion); that is, no native toolkit is in use.
+        Note that if GetPortId() returns @c wxPORT_BASE, then this value is zero
-        See wxAppTraits::GetToolkitVersion for more info.
+        (unless externally modified with SetToolkitVersion()); that is, no native
+        toolkit is in use.
+        See wxAppTraits::GetToolkitVersion() for more info.
 
         @see CheckToolkitVersion()
     */
@@ -182,9 +342,11 @@ public:
     /**
         Returns the run-time minor version of the toolkit associated with this
         wxPlatformInfo instance.
-        Note that if GetPortId() returns wxPORT_BASE, then this value is zero (unless
+
-        externally modified with wxPlatformInfo::SetToolkitVersion); that is, no native toolkit is in use.
+        Note that if GetPortId() returns @c wxPORT_BASE, then this value is zero
-        See wxAppTraits::GetToolkitVersion for more info.
+        (unless externally modified with SetToolkitVersion()); that is, no native
+        toolkit is in use.
+        See wxAppTraits::GetToolkitVersion() for more info.
 
         @see CheckToolkitVersion()
     */