revised st*.h headers

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

interface/wx/stackwalk.h

@@ -11,36 +11,33 @@
 
     wxStackWalker allows an application to enumerate, or walk, the stack frames
     (the function callstack).
-    It is mostly useful in only two situations:
-    inside wxApp::OnFatalException function to
-    programmatically get the location of the crash and, in debug builds, in
-    wxApp::OnAssertFailure to report the caller of the failed
-    assert.
 
-    wxStackWalker works by repeatedly calling
+    It is mostly useful in only two situations: inside wxApp::OnFatalException
-    the wxStackWalker::OnStackFrame method for each frame in the
+    function to programmatically get the location of the crash and, in debug builds,
-    stack, so to use it you must derive your own class from it and override this
+    in wxApp::OnAssertFailure to report the caller of the failed assert.
-    method.
+
+    wxStackWalker works by repeatedly calling the wxStackWalker::OnStackFrame
+    method for each frame in the stack, so to use it you must derive your own
+    class from it and override this method.
 
     This class will not return anything except raw stack frame addresses if the
     debug information is not available. Under Win32 this means that the PDB file
-    matching the program being executed should be present. Note that if you use
+    matching the program being executed should be present.
-    Microsoft Visual C++ compiler, you can create PDB files even for the programs
+    Note that if you use Microsoft Visual C++ compiler, you can create PDB files
-    built in release mode and it doesn't affect the program size (at least if you
+    even for the programs built in release mode and it doesn't affect the program
-    don't forget to add @c /opt:ref option which is suppressed by using
+    size (at least if you don't forget to add @c /opt:ref option which is suppressed
-    @c /debug linker option by default but should be always enabled for
+    by using @c /debug linker option by default but should be always enabled for
-    release builds). Under Unix, you need to compile your program with debugging
+    release builds).
-    information (usually using @c -g compiler and linker options) to get the
+    Under Unix, you need to compile your program with debugging information
-    file and line numbers information, however function names should be available
+    (usually using @c -g compiler and linker options) to get the file and line
-    even without it. Of course, all this is only @true if you build using a recent
+    numbers information, however function names should be available even without it.
-    enough version of GNU libc which provides the @c backtrace() function
+    Of course, all this is only @true if you build using a recent enough version
-    needed to walk the stack.
+    of GNU libc which provides the @c backtrace() function needed to walk the stack.
 
-    @ref overview_debuggingoverview "debugging overview" for how to make it
+    See @ref overview_debugging for how to make it available.
-    available.
 
     @library{wxbase}
-    @category{FIXME}
+    @category{debugging}
 
     @see wxStackFrame
 */
@@ -48,8 +45,7 @@ class wxStackWalker
 {
 public:
     /**
-        Constructor does nothing, use Walk() to walk the
+        Constructor does nothing, use Walk() to walk the stack.
-        stack.
     */
     wxStackWalker();
 
@@ -69,14 +65,15 @@ public:
         number of them (this can be useful when Walk() is called from some known
         location and you don't want to see the first few frames anyhow; also
         notice that Walk() frame itself is not included if skip = 1).
+
         Up to @a maxDepth frames are walked from the innermost to the outermost one.
     */
     virtual void Walk(size_t skip = 1, size_t maxDepth = 200);
 
     /**
         Enumerate stack frames from the location of uncaught exception.
-        This method can only be called from
+        This method can only be called from wxApp::OnFatalException().
-        wxApp::OnFatalException.
+
         Up to @a maxDepth frames are walked from the innermost to the outermost one.
     */
     virtual void WalkFromException(size_t maxDepth = 200);
@@ -88,12 +85,11 @@ public:
     @class wxStackFrame
 
     wxStackFrame represents a single stack frame, or a single function in the call
-    stack, and is used exclusively together with
+    stack, and is used exclusively together with wxStackWalker, see there for a more
-    wxStackWalker, see there for a more detailed
+    detailed discussion.
-    discussion.
 
     @library{wxbase}
-    @category{FIXME}
+    @category{debugging}
 
     @see wxStackWalker
 */
@@ -106,10 +102,10 @@ public:
     void* GetAddress() const;
 
     /**
-        Return the name of the file containing this frame, empty if
+        Return the name of the file containing this frame, empty if unavailable
-        unavailable (typically because debug info is missing).
+        (typically because debug info is missing).
-        Use HasSourceLocation() to check whether
+
-        the file name is available.
+        Use HasSourceLocation() to check whether the file name is available.
     */
     wxString GetFileName() const;
 
@@ -131,8 +127,7 @@ public:
     wxString GetModule() const;
 
     /**
-        Return the unmangled (if possible) name of the function containing this
+        Return the unmangled (if possible) name of the function containing this frame.
-        frame.
     */
     wxString GetName() const;
 
@@ -143,11 +138,10 @@ public:
 
     /**
         Get the name, type and value (in text form) of the given parameter.
-        Any pointer may be @NULL if you're not interested in the corresponding
+        Any pointer may be @NULL if you're not interested in the corresponding value.
-        value.
+
         Return @true if at least some values could be retrieved.
-        This function currently is only implemented under Win32 and requires a PDB
+        This function currently is only implemented under Win32 and requires a PDB file.
-        file.
     */
     bool GetParam(size_t n, wxString* type, wxString* name,
                   wxString* value) const;

interface/wx/statbmp.h

@@ -13,8 +13,9 @@
     platforms are only meant for display of the small icons in the dialog
     boxes. In particular, under Windows 9x the size of bitmap is limited
     to 64*64 pixels.
+
     If you want to display larger images portably, you may use generic
-    implementation wxGenericStaticBitmap declared in <wx/generic/statbmpg.h>.
+    implementation wxGenericStaticBitmap declared in \<wx/generic/statbmpg.h\>.
 
     @library{wxcore}
     @category{ctrl}
@@ -68,18 +69,18 @@ public:
                 const wxString& name = "staticBitmap");
 
     /**
-        Returns the bitmap currently used in the control. Notice that this method can
+        Returns the bitmap currently used in the control.
-        be called even if SetIcon() had been used.
+        Notice that this method can be called even if SetIcon() had been used.
 
         @see SetBitmap()
     */
     virtual wxBitmap GetBitmap() const;
 
     /**
-        Returns the icon currently used in the control. Notice that this method can
+        Returns the icon currently used in the control.
-        only be called if SetIcon() had been used: an icon
+        Notice that this method can only be called if SetIcon() had been used: an icon
-        can't be retrieved from the control if a bitmap had been set (using
+        can't be retrieved from the control if a bitmap had been set
-        wxStaticBitmap::SetBitmap).
+        (using wxStaticBitmap::SetBitmap).
 
         @see SetIcon()
     */

interface/wx/statbox.h

@@ -46,11 +46,11 @@ public:
         @param label
             Text to be displayed in the static box, the empty string for no label.
         @param pos
-            Window position. If wxDefaultPosition is specified then a default
+            Window position.
-        position is chosen.
+            If wxDefaultPosition is specified then a default position is chosen.
         @param size
-            Checkbox size. If the size (-1, -1) is specified then a default size is
+            Checkbox size.
-        chosen.
+            If wxDefaultSize is specified then a default size is chosen.
         @param style
             Window style. See wxStaticBox.
         @param name
@@ -71,8 +71,8 @@ public:
     virtual ~wxStaticBox();
 
     /**
-        Creates the static box for two-step construction. See wxStaticBox()
+        Creates the static box for two-step construction.
-        for further details.
+        See wxStaticBox() for further details.
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxString& label,

interface/wx/statline.h

@@ -25,7 +25,7 @@
     @endStyleTable
 
     @library{wxcore}
-    @category{FIXME}
+    @category{ctrl}
 
     @see wxStaticBox
 */
@@ -45,8 +45,8 @@ public:
         @param id
             Window identifier. The value wxID_ANY indicates a default value.
         @param pos
-            Window position. If wxDefaultPosition is specified then a default
+            Window position.
-        position is chosen.
+            If wxDefaultPosition is specified then a default position is chosen.
         @param size
             Size. Note that either the height or the width (depending on
             whether the line if horizontal or vertical) is ignored.
@@ -64,8 +64,8 @@ public:
                  const wxString& name = "staticLine");
 
     /**
-        Creates the static line for two-step construction. See wxStaticLine()
+        Creates the static line for two-step construction.
-        for further details.
+        See wxStaticLine() for further details.
     */
     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
                 const wxPoint& pos = wxDefaultPosition,

interface/wx/stattext.h

@@ -90,32 +90,33 @@ public:
 
     /**
         Returns the contents of the control.
-        Note that the returned string contains both the mnemonics (@c  characters),
+
+        Note that the returned string contains both the mnemonics (@& characters),
         if any, and markup tags, if any.
-        Use GetLabelText() if only the
+        Use GetLabelText() if only the label text is needed.
-        label text is needed.
     */
     wxString GetLabel() const;
 
-    //@{
     /**
-        The first form returns the control's label without the mnemonics characters (if
+        This method returns the control's label without the mnemonics characters
-        any)
+        (if any) and without the markup (if the control has @c wxST_MARKUP style).
-        and without the markup (if the control has @c wxST_MARKUP style).
-        The second (static) version returns the given @a label string without the
-        mnemonics
-        characters (if any) and without the markup.
     */
-    wxString GetLabelText();
+    wxString GetLabelText() const;
-    const static wxString  GetLabelText(const wxString& label);
+
-    //@}
+    /**
+        This overload returns the given @a label string without the
+        mnemonics characters (if any) and without the markup.
+    */
+    static wxString GetLabelText(const wxString& label);
 
     /**
         Sets the static text label and updates the controls size to exactly fit the
         label unless the control has wxST_NO_AUTORESIZE flag.
+
         This function allows to set decorated static label text on platforms which
         support it (currently only GTK+ 2). For the other platforms, the markup is
         ignored.
+
         The supported tags are:
         <TABLE>
             <TR>
@@ -156,14 +157,16 @@ public:
             </TR>
             <TR>
                 <TD>&lt;span&gt;</TD>
-                <TD>generic formatter tag; see Pango Markup for more information.</TD>
+                <TD>generic formatter tag; see Pango Markup
+                    (http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html)
+                    for more information.</TD>
             </TR>
         </TABLE>
 
         Note that the string must be well-formed (e.g. all tags must be correctly
-        closed)
+        closed) otherwise it can be not shown correctly or at all.
-        otherwise it can be not shown correctly or at all.
         Also note that you need to escape the following special characters:
+
         <TABLE>
             <TR>
                 <TD>@b Special character</TD>
@@ -197,16 +200,17 @@ public:
         Example:
 
         @param label
-            The new label to set. It may contain newline characters and the markup tags
+            The new label to set.
-        described above.
+            It may contain newline characters and the markup tags described above.
     */
     virtual void SetLabel(const wxString& label);
 
     /**
         This functions wraps the controls label so that each of its lines becomes at
         most @a width pixels wide if possible (the lines are broken at words
-        boundaries so it might not be the case if words are too long). If @e width
+        boundaries so it might not be the case if words are too long).
-        is negative, no wrapping is done. Note that this width is not
+
+        If @a width is negative, no wrapping is done. Note that this width is not
         necessarily the total width of the control, since a few pixels for the
         border (depending on the controls border style) may be added.
 

interface/wx/statusbr.h

@@ -10,55 +10,53 @@
     @class wxStatusBar
 
     A status bar is a narrow window that can be placed along the bottom of a frame
-    to give
+    to give small amounts of status information. It can contain one or more fields,
-    small amounts of status information. It can contain one or more fields, one or
+    one or more of which can be variable length according to the size of the window.
-    more of which can
-    be variable length according to the size of the window.
-
-    wxWindow
-
-    wxEvtHandler
-
-    wxObject
 
     @beginStyleTable
     @style{wxST_SIZEGRIP}
-           On Windows 95, displays a gripper at right-hand side of the status
+        On Windows 95, displays a gripper at right-hand side of the status bar.
-           bar.
     @endStyleTable
 
+    @todo reference to win95 may be old and wrong
+
+    @remarks
+    It is possible to create controls and other windows on the status bar.
+    Position these windows from an OnSize event handler.
+
     @library{wxcore}
     @category{miscwnd}
 
-    @see wxFrame, @ref overview_samplestatbar "Status bar sample"
+    @see wxFrame, @ref page_samples_statbar
 */
 class wxStatusBar : public wxWindow
 {
 public:
-    //@{
+    /**
+        Default ctor.
+    */
+    wxStatusBar();
+
     /**
         Constructor, creating the window.
 
         @param parent
             The window parent, usually a frame.
         @param id
-            The window identifier. It may take a value of -1 to indicate a default
+            The window identifier.
-        value.
+            It may take a value of -1 to indicate a default value.
         @param style
             The window style. See wxStatusBar.
         @param name
             The name of the window. This parameter is used to associate a name with the
-        item,
+            item, allowing the application user to set Motif resource values for
-            allowing the application user to set Motif resource values for
             individual windows.
 
         @see Create()
     */
-    wxStatusBar();
     wxStatusBar(wxWindow* parent, wxWindowID id = wxID_ANY,
                 long style = wxST_SIZEGRIP,
                 const wxString& name = "statusBar");
-    //@}
 
     /**
         Destructor.
@@ -99,7 +97,7 @@ public:
             The number of the status field to retrieve, starting from zero.
 
         @return The status field string if the field is valid, otherwise the
-                 empty string.
+                empty string.
 
         @see SetStatusText()
     */
@@ -126,64 +124,31 @@ public:
             The number of fields.
         @param widths
             An array of n integers interpreted in the same way as
-            in SetStatusWidths
+            in SetStatusWidths().
     */
     virtual void SetFieldsCount(int number = 1, int* widths = NULL);
 
     /**
-        Sets the minimal possible height for the status bar. The real height may be
+        Sets the minimal possible height for the status bar.
-        bigger than the height specified here depending on the size of the font used by
+
-        the status bar.
+        The real height may be bigger than the height specified here depending
+        on the size of the font used by the status bar.
     */
     virtual void SetMinHeight(int height);
 
     /**
         Sets the styles of the fields in the status line which can make fields appear
-        flat
+        flat or raised instead of the standard sunken 3D border.
-        or raised instead of the standard sunken 3D border.
 
         @param n
             The number of fields in the status bar. Must be equal to the
-            number passed to SetFieldsCount the last
+            number passed to SetFieldsCount() the last time it was called.
-            time it was called.
         @param styles
             Contains an array of n integers with the styles for each field. There
             are three possible styles:
-
+            - wxSB_NORMAL (default): The field appears sunken with a standard 3D border.
-
+            - wxSB_FLAT: No border is painted around the field so that it appears flat.
-
+            - wxSB_RAISED: A raised 3D border is painted around the field.
-
-
-
-
-            wxSB_NORMAL
-
-
-
-
-            (default) The field appears sunken with a standard 3D border.
-
-
-
-
-
-            wxSB_FLAT
-
-
-
-
-            No border is painted around the field so that it appears flat.
-
-
-
-
-
-            wxSB_RAISED
-
-
-
-
-            A raised 3D border is painted around the field.
     */
     virtual void SetStatusStyles(int n, int* styles);
 
@@ -207,25 +172,24 @@ public:
         the space left for all variable width fields is divided between them according
         to the absolute value of this number. A variable width field with width of -2
         gets twice as much of it as a field with width -1 and so on.
+
         For example, to create one fixed width field of width 100 in the right part of
         the status bar and two more fields which get 66% and 33% of the remaining
         space correspondingly, you should use an array containing -2, -1 and 100.
 
         @param n
             The number of fields in the status bar. Must be equal to the
-            number passed to SetFieldsCount the last
+            number passed to SetFieldsCount() the last time it was called.
-            time it was called.
         @param widths
-            Contains an array of n integers, each of which is
+            Contains an array of n integers, each of which is either an
-            either an absolute status field width in pixels if positive or indicates a
+            absolute status field width in pixels if positive or indicates a
             variable width field if negative.
 
         @remarks The widths of the variable fields are calculated from the total
                  width of all fields, minus the sum of widths of the
-                 non-variable fields, divided by the number of variable
+                 non-variable fields, divided by the number of variable fields.
-                 fields.
 
-        @see SetFieldsCount(), wxFrame::SetStatusWidths
+        @see SetFieldsCount(), wxFrame::SetStatusWidths()
     */
     virtual void SetStatusWidths(int n, int* widths);
 };

interface/wx/stc/stc.h

@@ -11,17 +11,17 @@
 
     The type of events sent from wxStyledTextCtrl.
 
-    TODO
+    @todo list styled text ctrl events.
 
     @library{wxbase}
-    @category{FIXME}
+    @category{events}
 */
 class wxStyledTextEvent : public wxCommandEvent
 {
 public:
     //@{
     /**
-        
+        Ctors; used internally by wxWidgets.
     */
     wxStyledTextEvent(wxEventType commandType = 0, int id = 0);
     wxStyledTextEvent(const wxStyledTextEvent& event);
@@ -29,11 +29,6 @@ public:
 
     /**
 
-    */
-    wxEvent* Clone() const;
-
-    /**
-        
     */
     bool GetAlt() const;
 
@@ -256,19 +251,72 @@ public:
     A wxWidgets implementation of the Scintilla source code editing component.
 
     As well as features found in standard text editing components, Scintilla
-    includes
+    includes features especially useful when editing and debugging source code.
-    features especially useful when editing and debugging source code. These
+    These include support for syntax styling, error indicators, code completion
-    include
+    and call tips.
-    support for syntax styling, error indicators, code completion and call tips.
+
-    The
+    The selection margin can contain markers like those used in debuggers to indicate
-    selection margin can contain markers like those used in debuggers to indicate
     breakpoints and the current line. Styling choices are more open than with many
     editors, allowing the use of proportional fonts, bold and italics, multiple
     foreground and background colours and multiple fonts.
 
     wxStyledTextCtrl is a 1 to 1 mapping of "raw" scintilla interface, whose
-    documentation
+    documentation can be found in the Scintilla website (http://www.scintilla.org/).
-    can be found in the Scintilla website.
+
+    @beginEventTable{wxStyledTextEvent}
+    @event{EVT_STC_CHANGE(id, fn)}
+        TOWRITE
+    @event{EVT_STC_STYLENEEDED(id, fn)}
+        TOWRITE
+    @event{EVT_STC_CHARADDED(id, fn)}
+        TOWRITE
+    @event{EVT_STC_SAVEPOINTREACHED(id, fn)}
+        TOWRITE
+    @event{EVT_STC_SAVEPOINTLEFT(id, fn)}
+        TOWRITE
+    @event{EVT_STC_ROMODIFYATTEMPT(id, fn)}
+        TOWRITE
+    @event{EVT_STC_KEY(id, fn)}
+        TOWRITE
+    @event{EVT_STC_DOUBLECLICK(id, fn)}
+        TOWRITE
+    @event{EVT_STC_UPDATEUI(id, fn)}
+        TOWRITE
+    @event{EVT_STC_MODIFIED(id, fn)}
+        TOWRITE
+    @event{EVT_STC_MACRORECORD(id, fn)}
+        TOWRITE
+    @event{EVT_STC_MARGINCLICK(id, fn)}
+        TOWRITE
+    @event{EVT_STC_NEEDSHOWN(id, fn)}
+        TOWRITE
+    @event{EVT_STC_PAINTED(id, fn)}
+        TOWRITE
+    @event{EVT_STC_USERLISTSELECTION(id, fn)}
+        TOWRITE
+    @event{EVT_STC_URIDROPPED(id, fn)}
+        TOWRITE
+    @event{EVT_STC_DWELLSTART(id, fn)}
+        TOWRITE
+    @event{EVT_STC_DWELLEND(id, fn)}
+        TOWRITE
+    @event{EVT_STC_START_DRAG(id, fn)}
+        TOWRITE
+    @event{EVT_STC_DRAG_OVER(id, fn)}
+        TOWRITE
+    @event{EVT_STC_DO_DROP(id, fn)}
+        TOWRITE
+    @event{EVT_STC_ZOOM(id, fn)}
+        TOWRITE
+    @event{EVT_STC_HOTSPOT_CLICK(id, fn)}
+        TOWRITE
+    @event{EVT_STC_HOTSPOT_DCLICK(id, fn)}
+        TOWRITE
+    @event{EVT_STC_CALLTIP_CLICK(id, fn)}
+        TOWRITE
+    @event{EVT_STC_AUTOCOMP_SELECTION(id, fn)}
+        TOWRITE
+    @endEventTable
 
     @library{wxbase}
     @category{stc}
@@ -299,9 +347,6 @@ public:
     void AddStyledText(const wxMemoryBuffer& data);
 
     /**
-        BEGIN generated section.  The following code is automatically generated
-        by gen_iface.py.  Do not edit this file.  Edit stc.h.in instead
-        and regenerate
         Add text to the document at current position.
     */
     void AddText(const wxString& text);
@@ -461,8 +506,7 @@ public:
     void AutoCompSetSeparator(int separatorCharacter);
 
     /**
-        Change the type-separator character in the string setting up an auto-completion
+        Change the type-separator character in the string setting up an auto-completion list.
-        list.
         Default is '?' but can be changed if items contain '?'.
     */
     void AutoCompSetTypeSeparator(int separatorCharacter);
@@ -1407,8 +1451,7 @@ public:
         except they behave differently when word-wrap is enabled:
         They go first to the start / end of the display line, like (Home|LineEnd)Display
         The difference is that, the cursor is already at the point, it goes on to the
-        start
+        start or end of the document line, as appropriate for (Home|LineEnd|VCHome)(Extend)?.
-        or end of the document line, as appropriate for (Home|LineEnd|VCHome)(Extend)?.
     */
     void HomeWrap();
 
@@ -1790,17 +1833,14 @@ public:
     int ReplaceTarget(const wxString& text);
 
     /**
-        Replace the target text with the argument text after
+        Replace the target text with the argument text after d processing.
-        d processing.
         Text is counted so it can contain NULs.
-        Looks for
+
-        d where d is between 1 and 9 and replaces these with the strings
+        Looks for d where d is between 1 and 9 and replaces these with the strings
-        matched in the last search operation which were surrounded by
+        matched in the last search operation which were surrounded by ( and ).
-        ( and
+
-        ).
         Returns the length of the replacement text including any change
-        caused by processing the
+        caused by processing the d patterns.
-        d patterns.
     */
     int ReplaceTargetRE(const wxString& text);
 

interface/wx/stdpaths.h

@@ -16,17 +16,16 @@
     for the Unix, Windows and Mac OS X systems, however please note that these are
     just the examples and the actual values may differ. For example, under Windows:
     the system administrator may change the standard directories locations, i.e.
-    the Windows directory may be named @c W:\\Win2003 instead of
+    the Windows directory may be named @c "W:\Win2003" instead of
-    the default @c C:\\Windows.
+    the default @c "C:\Windows".
 
-    The strings @c appname and @c username should be
+    The strings @c appname and @c username should be replaced with the value
-    replaced with the value returned by wxApp::GetAppName
+    returned by wxApp::GetAppName() and the name of the currently logged in user,
-    and the name of the currently logged in user, respectively. The string
+    respectively. The string @c prefix is only used under Unix and is @c /usr/local by
-    @c prefix is only used under Unix and is @c /usr/local by
     default but may be changed using wxStandardPaths::SetInstallPrefix.
 
-    The directories returned by the methods of this class may or may not exist. If
+    The directories returned by the methods of this class may or may not exist.
-    they don't exist, it's up to the caller to create them, wxStandardPaths doesn't
+    If they don't exist, it's up to the caller to create them, wxStandardPaths doesn't
     do it.
 
     Finally note that these functions only work with standardly packaged
@@ -45,7 +44,7 @@
     @category{file}
 
     @see wxFileConfig
-        */
+*/
 class wxStandardPaths
 {
 public:
@@ -57,9 +56,9 @@ public:
     /**
         Return the directory containing the system config files.
         Example return values:
-             - Unix: @c /etc
+        - Unix: @c /etc
-             - Windows: @c C:\\Documents @c and @c Settings\\All @c Users\\Application Data
+        - Windows: @c "C:\Documents and Settings\All Users\Application Data"
-             - Mac: @c /Library/Preferences
+        - Mac: @c /Library/Preferences
 
         @see wxFileConfig
     */
@@ -69,9 +68,9 @@ public:
         Return the location of the applications global, i.e. not user-specific,
         data files.
         Example return values:
-             - Unix: @c prefix/share/appname
+        - Unix: @c prefix/share/appname
-             - Windows: the directory where the executable file is located
+        - Windows: the directory where the executable file is located
-             - Mac: @c appname.app/Contents/SharedSupport bundle subdirectory
+        - Mac: @c appname.app/Contents/SharedSupport bundle subdirectory
 
         @see GetLocalDataDir()
     */
@@ -80,9 +79,9 @@ public:
     /**
         Return the directory containing the current user's documents.
         Example return values:
-             - Unix: @c ~ (the home directory)
+        - Unix: @c ~ (the home directory)
-             - Windows: @c C:\\Documents @c and @c Settings\\username\\My Documents
+        - Windows: @c "C:\Documents and Settings\username\My Documents"
-             - Mac: @c ~/Documents
+        - Mac: @c ~/Documents
 
         @since 2.7.0
     */
@@ -91,36 +90,38 @@ public:
     /**
         Return the directory and the filename for the current executable.
         Example return values:
-             - Unix: @c /usr/local/bin/exename
+        - Unix: @c /usr/local/bin/exename
-             - Windows: @c C:\\Programs\\AppFolder\\exename.exe
+        - Windows: @c "C:\Programs\AppFolder\exename.exe"
-             - Mac: @c /Programs/exename
+        - Mac: @c /Programs/exename
     */
     virtual wxString GetExecutablePath() const;
 
     /**
-        @note This function is only available under Unix.
+        Return the program installation prefix, e.g. @c /usr, @c /opt or @c /home/zeitlin.
-        Return the program installation prefix, e.g. @c /usr, @c /opt or
+
-        @c /home/zeitlin.
         If the prefix had been previously by SetInstallPrefix(), returns that
-        value, otherwise tries to determine it automatically (Linux only right
+        value, otherwise tries to determine it automatically (Linux only right now)
-        now) and finally returns the default @c /usr/local value if it failed.
+        and finally returns the default @c /usr/local value if it failed.
+
+        @note This function is only available under Unix.
     */
     wxString GetInstallPrefix() const;
 
     /**
         Return the location for application data files which are host-specific and
         can't, or shouldn't, be shared with the other machines.
-        This is the same as GetDataDir() except
+
-        under Unix where it returns @c /etc/appname.
+        This is the same as GetDataDir() except under Unix where it returns @c /etc/appname.
     */
     virtual wxString GetLocalDataDir() const;
 
     /**
         Return the localized resources directory containing the resource files of the
         specified category for the given language.
-        In general this is just the same as @a lang subdirectory of
+
-        GetResourcesDir() (or @c lang.lproj under Mac OS X) but is something quite
+        In general this is just the same as @a lang subdirectory of GetResourcesDir()
-        different for message catalog category under Unix where it returns the standard
+        (or @c lang.lproj under Mac OS X) but is something quite different for
+        message catalog category under Unix where it returns the standard
         @c prefix/share/locale/lang/LC_MESSAGES directory.
 
         @since 2.7.0
@@ -131,24 +132,25 @@ public:
     /**
         Return the directory where the loadable modules (plugins) live.
         Example return values:
-             - Unix: @c prefix/lib/appname
+        - Unix: @c prefix/lib/appname
-             - Windows: the directory of the executable file
+        - Windows: the directory of the executable file
-             - Mac: @c appname.app/Contents/PlugIns bundle subdirectory
+        - Mac: @c appname.app/Contents/PlugIns bundle subdirectory
 
         @see wxDynamicLibrary
     */
     virtual wxString GetPluginsDir() const;
 
     /**
-        Return the directory where the application resource files are located. The
+        Return the directory where the application resource files are located.
-        resources are the auxiliary data files needed for the application to run and
+
-        include, for example, image and sound files it might use.
+        The resources are the auxiliary data files needed for the application to run
-        This function is the same as GetDataDir() for
+        and include, for example, image and sound files it might use.
-        all platforms except Mac OS X.
+
+        This function is the same as GetDataDir() for all platforms except Mac OS X.
         Example return values:
-             - Unix: @c prefix/share/@e appname
+        - Unix: @c prefix/share/appname
-             - Windows: the directory where the executable file is located
+        - Windows: the directory where the executable file is located
-             - Mac: @c appname.app/Contents/Resources bundle subdirectory
+        - Mac: @c appname.app/Contents/Resources bundle subdirectory
 
         @since 2.7.0
 
@@ -157,10 +159,9 @@ public:
     virtual wxString GetResourcesDir() const;
 
     /**
-        Return the directory for storing temporary files. To create unique temporary
+        Return the directory for storing temporary files.
-        files,
+        To create unique temporary files, it is best to use wxFileName::CreateTempFileName
-        it is best to use wxFileName::CreateTempFileName for correct behaviour when
+        for correct behaviour when multiple processes are attempting to create temporary files.
-        multiple processes are attempting to create temporary files.
 
         @since 2.7.2
     */
@@ -168,40 +169,42 @@ public:
 
     /**
         Return the directory for the user config files:
-             - Unix: @c ~ (the home directory)
+        - Unix: @c ~ (the home directory)
-             - Windows: @c C:\\Documents @c and @c Settings\\username\\Application Data
+        - Windows: @c "C:\Documents and Settings\username\Application Data"
-             - Mac: @c ~/Library/Preferences
+        - Mac: @c ~/Library/Preferences
+
         Only use this method if you have a single configuration file to put in this
-        directory, otherwise GetUserDataDir() is
+        directory, otherwise GetUserDataDir() is more appropriate.
-        more appropriate.
     */
     virtual wxString GetUserConfigDir() const;
 
     /**
         Return the directory for the user-dependent application data files:
-             - Unix: @c ~/.appname
+        - Unix: @c ~/.appname
-             - Windows: @c C:\\Documents @c and @c Settings\\username\\Application @c Data\\appname
+        - Windows: @c "C:\Documents and Settings\username\Application Data\appname"
-             - Mac: @c ~/Library/Application @c Support/appname
+        - Mac: @c "~/Library/Application Support/appname"
     */
     virtual wxString GetUserDataDir() const;
 
     /**
         Return the directory for user data files which shouldn't be shared with
         the other machines.
+
         This is the same as GetUserDataDir() for all platforms except Windows where it returns
-        @c C:\\Documents @c and @c Settings\\username\\Local @c Settings\\Application @c Data\\appname
+        @c "C:\Documents and Settings\username\Local Settings\Application Data\appname"
     */
     virtual wxString GetUserLocalDataDir() const;
 
     /**
-        @note This function is only available under Unix.
         Lets wxStandardPaths know about the real program installation prefix on a Unix
-        system. By default, the value returned by
+        system. By default, the value returned by GetInstallPrefix() is used.
-        GetInstallPrefix() is used.
+
         Although under Linux systems the program prefix may usually be determined
         automatically, portable programs should call this function. Usually the prefix
         is set during program configuration if using GNU autotools and so it is enough
         to pass its value defined in @c config.h to this function.
+
+        @note This function is only available under Unix.
     */
     void SetInstallPrefix(const wxString& prefix);
 
@@ -209,10 +212,11 @@ public:
         Controls what application information is used when constructing paths that
         should be unique to this program, such as the application data directory, the
         plugins directory on Unix, etc.
-        Valid values for @a info are @c AppInfo_None and either one or
+
-        combination of @c AppInfo_AppName and @c AppInfo_VendorName. The
+        Valid values for @a info are @c AppInfo_None and either one or combination
-        first one tells this class to not use neither application nor vendor name in
+        of @c AppInfo_AppName and @c AppInfo_VendorName. The first one tells this
-        the paths.
+        class to not use neither application nor vendor name in the paths.
+
         By default, only the application name is used under Unix systems but both
         application and vendor names are used under Windows and Mac.
     */

interface/wx/stopwatch.h

@@ -9,11 +9,12 @@
 /**
     @class wxStopWatch
 
-    The wxStopWatch class allow you to measure time intervals. For example, you may
+    The wxStopWatch class allow you to measure time intervals.
-    use it to measure the time elapsed by some function:
+
+    For example, you may use it to measure the time elapsed by some function:
 
     @code
-    wxStopWatch sw;
+        wxStopWatch sw;
         CallLongRunningFunction();
         wxLogMessage("The long running function took %ldms to execute",
                      sw.Time());
@@ -38,8 +39,8 @@ public:
     wxStopWatch();
 
     /**
-        Pauses the stop watch. Call Resume() to resume
+        Pauses the stop watch. Call Resume() to resume time measuring again.
-        time measuring again.
+
         If this method is called several times, @c Resume() must be called the same
         number of times to really resume the stop watch. You may, however, call
         Start() to resume it unconditionally.
@@ -47,8 +48,7 @@ public:
     void Pause();
 
     /**
-        Resumes the stop watch which had been paused with
+        Resumes the stop watch which had been paused with Pause().
-        Pause().
     */
     void Resume();
 
@@ -58,9 +58,8 @@ public:
     void Start(long milliseconds = 0);
 
     /**
-        Returns the time in milliseconds since the start (or restart) or the last call
+        Returns the time in milliseconds since the start (or restart) or the last
-        of
+        call of Pause().
-        Pause().
     */
     long Time() const;
 };

interface/wx/strconv.h

@@ -30,7 +30,7 @@
     @library{wxbase}
     @category{conv}
 
-    @see wxCSConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview"
+    @see wxCSConv, wxEncodingConverter, @ref overview_mbconv
 */
 class wxMBConv
 {
@@ -116,10 +116,11 @@ public:
             @a dst is non-@NULL, unused otherwise.
         @param src
             Point to the source string, must not be @NULL.
-        @param
+        @param srcLen
-            The number of characters of the source string to convert or @c
+            The number of characters of the source string to convert or
-            wxNO_LEN (default parameter) to convert everything up to and
+            @c wxNO_LEN (default parameter) to convert everything up to and
             including the terminating @c NUL character(s).
+
         @return
             The number of character written (or which would have been written
             if it were non-@NULL) to @a dst or @c wxCONV_FAILED on error.
@@ -143,10 +144,11 @@ public:
             @a dst is non-@NULL, unused otherwise.
         @param src
             Point to the source string, must not be @NULL.
-        @param
+        @param srcLen
-            The number of characters of the source string to convert or @c
+            The number of characters of the source string to convert or
-            wxNO_LEN (default parameter) to convert everything up to and
+            @c wxNO_LEN (default parameter) to convert everything up to and
             including the terminating @c NUL character.
+
         @return
             The number of character written (or which would have been written
             if it were non-@NULL) to @a dst or @c wxCONV_FAILED on error.
@@ -301,7 +303,7 @@ public:
     @library{wxbase}
     @category{conv}
 
-    @see wxMBConvUTF8, @ref overview_mbconv "wxMBConv classes overview"
+    @see wxMBConvUTF8, @ref overview_mbconv
 */
 class wxMBConvUTF7 : public wxMBConv
 {
@@ -318,7 +320,7 @@ class wxMBConvUTF7 : public wxMBConv
     @library{wxbase}
     @category{conv}
 
-    @see wxMBConvUTF7, @ref overview_mbconv "wxMBConv classes overview"
+    @see wxMBConvUTF7, @ref overview_mbconv
 */
 class wxMBConvUTF8 : public wxMBConv
 {
@@ -341,7 +343,7 @@ class wxMBConvUTF8 : public wxMBConv
     @library{wxbase}
     @category{conv}
 
-    @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv "wxMBConv classes overview"
+    @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv
 */
 class wxMBConvUTF16 : public wxMBConv
 {
@@ -362,7 +364,7 @@ class wxMBConvUTF16 : public wxMBConv
     @library{wxbase}
     @category{conv}
 
-    @see wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconv "wxMBConv classes overview"
+    @see wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconv
 */
 class wxMBConvUTF32 : public wxMBConv
 {
@@ -389,7 +391,7 @@ class wxMBConvUTF32 : public wxMBConv
     @library{wxbase}
     @category{conv}
 
-    @see wxMBConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview"
+    @see wxMBConv, wxEncodingConverter, @ref overview_mbconv
 */
 class wxCSConv : public wxMBConv
 {
@@ -466,7 +468,7 @@ public:
     @library{wxbase}
     @category{conv}
 
-    @see @ref overview_mbconv "wxMBConv classes overview"
+    @see @ref overview_mbconv
 */
 class wxMBConvFile : public wxMBConv
 {

interface/wx/stream.h

@@ -115,6 +115,7 @@ public:
     /**
         Constructor; creates a new empty stream buffer which won't flush any data
         to a stream. mode specifies the type of the buffer (read, write, read_write).
+
         This stream buffer has the advantage to be stream independent and to work
         only on memory buffers but it is still compatible with the rest of the
         wxStream classes. You can write, read to this special stream and it will
@@ -129,7 +130,9 @@ public:
     wxStreamBuffer(BufMode mode);
 
     /**
-        Constructor. It initializes the stream buffer with the data of the specified
+        Constructor.
+
+        This method initializes the stream buffer with the data of the specified
         stream buffer. The new stream buffer has the same attributes, size, position
         and they share the same buffer. This will cause problems if the stream to
         which the stream buffer belong is destroyed and the newly cloned stream
@@ -450,7 +453,7 @@ enum wxStreamProtocolType
     handle it and create a stream to decompress it:
 
     @code
-    factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
+        factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
         if (factory)
             stream = factory-NewStream(new wxFFileInputStream(filename));
     @endcode

interface/wx/string.h

@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        string.h
-// Purpose:     interface of wxStringBuffer
+// Purpose:     interface of wxStringBuffer, wxString
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
@@ -9,21 +9,19 @@
 /**
     @class wxStringBuffer
 
-    This tiny class allows you to conveniently access the wxString
+    This tiny class allows you to conveniently access the wxString internal buffer
-    internal buffer as a writable pointer without any risk of forgetting to restore
+    as a writable pointer without any risk of forgetting to restore the string
-    the string to the usable state later.
+    to the usable state later.
 
     For example, assuming you have a low-level OS function called
-    @c GetMeaningOfLifeAsString(char *) returning the value in the provided
+    @c "GetMeaningOfLifeAsString(char *)" returning the value in the provided
     buffer (which must be writable, of course) you might call it like this:
 
     @code
-    wxString theAnswer;
+        wxString theAnswer;
         GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024));
         if ( theAnswer != "42" )
-        {
             wxLogError("Something is very wrong!");
-        }
     @endcode
 
     Note that the exact usage of this depends on whether or not wxUSE_STL is
@@ -41,15 +39,15 @@ class wxStringBuffer
 public:
     /**
         Constructs a writable string buffer object associated with the given string
-        and containing enough space for at least @a len characters. Basically, this
+        and containing enough space for at least @a len characters.
-        is equivalent to calling wxString::GetWriteBuf and
+        Basically, this is equivalent to calling wxString::GetWriteBuf() and
         saving the result.
     */
     wxStringBuffer(const wxString& str, size_t len);
 
     /**
         Restores the string passed to the constructor to the usable state by calling
-        wxString::UngetWriteBuf on it.
+        wxString::UngetWriteBuf() on it.
     */
     ~wxStringBuffer();
 
@@ -111,15 +109,14 @@ public:
     }
     @endcode
 
-    Please see the
+    Please see the @ref overview_string and the @ref overview_unicode for more
-    @ref overview_string "wxString overview" and the
+    information about it.
-    @ref overview_unicode "Unicode overview" for more information
-    about it.
 
     wxString uses the current locale encoding to convert any C string
     literal to Unicode. The same is done for converting to and from
-    @c std::string and for the return value of c_str(). For this
+    @c std::string and for the return value of c_str().
-    conversion, the @a wxConvLibc class instance is used. See wxCSConv and wxMBConv.
+    For this conversion, the @a wxConvLibc class instance is used.
+    See wxCSConv and wxMBConv.
 
     wxString implements most of the methods of the @c std::string class.
     These standard functions are only listed here, but they are not
@@ -132,172 +129,214 @@ public:
     all return the string length. In all cases of such duplication the
     @c std::string compatible method should be used.
 
+
+    @section string_construct Constructors and assignment operators
+
+    A string may be constructed either from a C string, (some number of copies of)
+    a single character or a wide (Unicode) string. For all constructors (except the
+    default which creates an empty string) there is also a corresponding assignment
+    operator.
+
+    @li wxString()
+    @li operator=()
+    @li ~wxString()
+    @li assign()
+
+
+    @section string_len String length
+
+    These functions return the string length and check whether the string
+    is empty or they empty it.
+
+    @li length()
+    @li size()
+    @li Len()
+    @li IsEmpty()
+    @li operator!()
+    @li Empty()
+    @li Clear()
+
+
+    @section string_access Character access
+
+    Many functions below take a character index in the string. As with C
+    strings and arrays, the indices start from 0, so the first character of a
+    string is string[0]. An attempt to access a character beyond the end of the
+    string (which may even be 0 if the string is empty) will provoke an assert
+    failure in @ref overview_debugging "debug builds", but no checks are
+    done in release builds.
+
+    This section also contains both implicit and explicit conversions to C style
+    strings. Although implicit conversion is quite convenient, you are advised
+    to use wc_str() for the sake of clarity.
+
+    @li GetChar()
+    @li GetWritableChar()
+    @li SetChar()
+    @li Last()
+    @li operator[]()
+    @li wc_str()
+    @li utf8_str()
+    @li c_str()
+    @li wx_str()
+    @li mb_str()
+    @li fn_str()
+
+
+    @section string_concat Concatenation
+
     Anything may be concatenated (appended to) with a string. However, you can't
     append something to a C string (including literal constants), so to do this it
     should be converted to a wxString first.
 
-        @li insert()
+    @li insert()
-        @li append()
+    @li append()
-        @li operator<<()
+    @li operator<<()
-        @li operator+=()
+    @li operator+=()
-        @li operator+()
+    @li operator+()
-        @li Append()
+    @li Append()
-        @li Prepend()
+    @li Prepend()
 
-        A string may be constructed either from a C string, (some number of copies of)
-        a single character or a wide (Unicode) string. For all constructors (except the
-        default which creates an empty string) there is also a corresponding assignment
-        operator.
 
-        @li wxString()
+    @section string_comp Comparison
-        @li operator=()
-        @li ~wxString()
-        @li assign()
 
-        The MakeXXX() variants modify the string in place, while the other functions
+    The default comparison function Cmp() is case-sensitive and so is the default
-        return a new string which contains the original text converted to the upper or
+    version of IsSameAs(). For case insensitive comparisons you should use CmpNoCase()
-        lower case and leave the original string unchanged.
+    or give a second parameter to IsSameAs(). This last function is maybe more
+    convenient if only equality of the strings matters because it returns a boolean
+    @true value if the strings are the same and not 0 (which is usually @false
+    in C) as Cmp() does.
 
-        @li MakeUpper()
+    Matches() is a poor man's regular expression matcher: it only understands
-        @li Upper()
+    '*' and '?' metacharacters in the sense of DOS command line interpreter.
-        @li MakeLower()
-        @li Lower()
-        @li MakeCapitalized()
-        @li Capitalize()
 
-        Many functions below take a character index in the string. As with C
+    StartsWith() is helpful when parsing a line of text which should start
-        strings and arrays, the indices start from 0, so the first character of a
+    with some predefined prefix and is more efficient than doing direct string
-        string is string[0]. An attempt to access a character beyond the end of the
+    comparison as you would also have to precalculate the length of the prefix.
-        string (which may even be 0 if the string is empty) will provoke an assert
-        failure in @ref overview_debugging "debug build", but no checks are
-        done in release builds.
-        This section also contains both implicit and explicit conversions to C style
-        strings. Although implicit conversion is quite convenient, you are advised
-        to use wc_str() for the sake of clarity.
 
-        @li GetChar()
+    @li compare()
-        @li GetWritableChar()
+    @li Cmp()
-        @li SetChar()
+    @li CmpNoCase()
-        @li Last()
+    @li IsSameAs()
-        @li operator[]()
+    @li Matches()
-        @li wc_str()
+    @li StartsWith()
-        @li utf8_str()
+    @li EndsWith()
-        @li c_str()
-        @li wx_str()
-        @li mb_str()
-        @li fn_str()
 
-        The default comparison function Cmp() is case-sensitive and so is the default
-        version of IsSameAs(). For case insensitive comparisons you should use CmpNoCase()
-        or give a second parameter to IsSameAs(). This last function is maybe more
-        convenient if only equality of the strings matters because it returns a boolean
-        @true value if the strings are the same and not 0 (which is usually @false
-        in C) as Cmp() does.
-        Matches() is a poor man's regular expression matcher: it only understands
-        '*' and '?' metacharacters in the sense of DOS command line interpreter.
-        StartsWith() is helpful when parsing a line of text which should start
-        with some predefined prefix and is more efficient than doing direct string
-        comparison as you would also have to precalculate the length of the prefix.
 
-        @li compare()
+    @section string_substring Substring extraction
-        @li Cmp()
-        @li CmpNoCase()
-        @li IsSameAs()
-        @li Matches()
-        @li StartsWith()
-        @li EndsWith()
 
-        The string provides functions for conversion to signed and unsigned integer and
+    These functions allow you to extract a substring from the string. The
-        floating point numbers. All functions take a pointer to the variable to
+    original string is not modified and the function returns the extracted
-        put the numeric value in and return @true if the @b entire string could be
+    substring.
-        converted to a number.
 
-        @li ToLong()
+    @li substr()
-        @li ToLongLong()
+    @li Mid()
-        @li ToULong()
+    @li operator()()
-        @li ToULongLong()
+    @li Left()
-        @li ToDouble()
+    @li Right()
+    @li BeforeFirst()
+    @li BeforeLast()
+    @li AfterFirst()
+    @li AfterLast()
+    @li StartsWith()
+    @li EndsWith()
 
-        The following are "advanced" functions and they will be needed rarely.
-        Alloc() and Shrink() are only interesting for optimization purposes.
-        wxStringBuffer and wxStringBufferLength classes may be very useful
-        when working with some external API which requires the caller to provide
-        a writable buffer.
 
-        @li reserve()
+    @section string_case Case conversion
-        @li resize()
-        @li Alloc()
-        @li Shrink()
-        @li wxStringBuffer
-        @li wxStringBufferLength
 
-        Miscellaneous other string functions.
+    The MakeXXX() variants modify the string in place, while the other functions
+    return a new string which contains the original text converted to the upper or
+    lower case and leave the original string unchanged.
 
-        @li Trim()
+    @li MakeUpper()
-        @li Truncate()
+    @li Upper()
-        @li Pad()
+    @li MakeLower()
+    @li Lower()
+    @li MakeCapitalized()
+    @li Capitalize()
 
-        These functions return the string length and check whether the string
-        is empty or they empty it.
 
-        @li length()
+    @section string_search Searching and replacing
-        @li size()
-        @li Len()
-        @li IsEmpty()
-        @li operator!()
-        @li Empty()
-        @li Clear()
 
-        These functions allow you to extract a substring from the string. The
+    These functions replace the standard @e strchr() and @e strstr()
-        original string is not modified and the function returns the extracted
+    functions.
-        substring.
 
-        @li substr()
+    @li find()
-        @li Mid()
+    @li rfind()
-        @li operator()()
+    @li replace()
-        @li Left()
+    @li Find()
-        @li Right()
+    @li Replace()
-        @li BeforeFirst()
-        @li BeforeLast()
-        @li AfterFirst()
-        @li AfterLast()
-        @li StartsWith()
-        @li EndsWith()
 
-        These functions replace the standard @e strchr() and @e strstr()
-        functions.
 
-        @li find()
+    @section string_conv Conversion to numbers
-        @li rfind()
-        @li replace()
-        @li Find()
-        @li Replace()
 
-        Both formatted versions (Printf/() and stream-like insertion operators
+    The string provides functions for conversion to signed and unsigned integer and
-        exist (for basic types only). Additionally, the Format() function allows
+    floating point numbers. All functions take a pointer to the variable to
-        you to simply append a formatted value to a string:
+    put the numeric value in and return @true if the @b entire string could be
+    converted to a number.
 
-        @li Format()
+    @li ToLong()
-        @li FormatV()
+    @li ToLongLong()
-        @li Printf()
+    @li ToULong()
-        @li PrintfV()
+    @li ToULongLong()
-        @li operator>>()
+    @li ToDouble()
 
-        The following functions are deprecated. Please consider using new wxWidgets 2.0
-        functions instead (or, even better, @c std::string compatible variants).
 
-        Contains(), First(), Freq(), IsAscii(), IsNull(),
+    @section string_fmt Writing values into the string
-        IsNumber(), IsWord(), Last(), Length(), LowerCase(), Remove(), Strip(),
+
-        SubString(), UpperCase()
+    Both formatted versions (Printf/() and stream-like insertion operators
+    exist (for basic types only). Additionally, the Format() function allows
+    you to simply append a formatted value to a string:
+
+    @li Format()
+    @li FormatV()
+    @li Printf()
+    @li PrintfV()
+    @li operator>>()
+
+
+    @section string_mem Memory management
+
+    The following are "advanced" functions and they will be needed rarely.
+    Alloc() and Shrink() are only interesting for optimization purposes.
+    wxStringBuffer and wxStringBufferLength classes may be very useful
+    when working with some external API which requires the caller to provide
+    a writable buffer.
+
+    @li reserve()
+    @li resize()
+    @li Alloc()
+    @li Shrink()
+    @li wxStringBuffer
+    @li wxStringBufferLength
+
+
+    @section string_misc Miscellaneous
+
+    Miscellaneous other string functions.
+
+    @li Trim()
+    @li Truncate()
+    @li Pad()
+
+
+    @section string_misc wxWidgets 1.xx compatibility functions
+
+    The following functions are deprecated.
+    Please consider using @c std::string compatible variants.
+
+    Contains(), First(), Freq(), IsAscii(), IsNull(),
+    IsNumber(), IsWord(), Last(), Length(), LowerCase(), Remove(), Strip(),
+    SubString(), UpperCase()
+
 
     @library{wxbase}
     @category{data}
 
     @stdobjects
-    ::Objects, ::wxEmptyString,
+    ::wxEmptyString
 
-    @see @ref overview_string "wxString overview", @ref overview_unicode
+    @see @ref overview_string, @ref overview_unicode, wxUString
-    "Unicode overview", wxUString
 */
 class wxString
 {
@@ -326,8 +365,8 @@ public:
     wxString();
 
     /**
-       Creates a string from another string. Just increases the ref
+       Creates a string from another string.
-       count by 1.
+        Just increases the ref count by 1.
     */
     wxString(const wxString& stringSrc);
 
@@ -367,8 +406,8 @@ public:
     wxString(const wchar_t *pwz, size_t nLength);
 
     /**
-       Constructs a string from @e buf using the using
+       Constructs a string from @e buf using the using the current locale
-       the current locale encoding to convert it to Unicode.
+        encoding to convert it to Unicode.
     */
     wxString(const wxCharBuffer& buf);
 
@@ -390,8 +429,9 @@ public:
 
 
     /**
-        String destructor. Note that this is not virtual, so wxString must not be
+        String destructor.
-        inherited from.
+
+        Note that this is not virtual, so wxString must not be inherited from.
     */
     ~wxString();
 
@@ -488,7 +528,6 @@ public:
     */
     wxString BeforeLast(wxUniChar ch) const;
 
-
     /**
         Return the copy of the string with the first string character in the
         upper case and the subsequent ones in the lower case.
@@ -1014,12 +1053,13 @@ public:
         Returns @true on success in which case the number is stored in the
         location pointed to by @a val or @false if the string does not
         represent a valid number in the given base (the value of @a val is not
-        modified in this case). Please notice that this function
+        modified in this case).
-        behaves in the same way as the standard @c strtoul() and so it simply
+
-        converts negative numbers to unsigned representation instead of rejecting them
+        Please notice that this function  behaves in the same way as the standard
-        (e.g. -1 is returned as @c ULONG_MAX).
+        @c strtoul() and so it simply converts negative numbers to unsigned
-        See ToLong() for the more detailed
+        representation instead of rejecting them (e.g. -1 is returned as @c ULONG_MAX).
-        description of the @a base parameter.
+
+        See ToLong() for the more detailed description of the @a base parameter.
 
         @see ToDouble(), ToLong()
     */
@@ -1054,16 +1094,16 @@ public:
     //@{
     /**
         Puts the string back into a reasonable state (in which it can be used
-        normally), after
+        normally), after GetWriteBuf() was called.
-        GetWriteBuf() was called.
+
         The version of the function without the @a len parameter will calculate the
         new string length itself assuming that the string is terminated by the first
         @c NUL character in it while the second one will use the specified length
         and thus is the only version which should be used with the strings with
         embedded @c NULs (it is also slightly more efficient as @c strlen()
         doesn't have to be called).
-        This method is deprecated, please use
+
-        wxStringBuffer or
+        This method is deprecated, please use wxStringBuffer or
         wxStringBufferLength instead.
     */
     void UngetWriteBuf();
@@ -1078,7 +1118,8 @@ public:
     wxString Upper() const;
 
     /**
-        The same as MakeUpper.
+        The same as MakeUpper().
+
         This is a wxWidgets 1.xx compatibility function; you should not use it in new
         code.
     */
@@ -1090,8 +1131,7 @@ public:
         Given this ambiguity it is mostly better to use wc_str(), mb_str() or
         utf8_str() instead.
 
-        Please see the @ref overview_unicode "Unicode overview" for more
+        Please see the @ref overview_unicode for more information about it.
-        information about it.
 
         Note that the returned value is not convertible to @c char* or
         @c wchar_t*, use char_str() or wchar_str() if you need to pass
@@ -1125,7 +1165,9 @@ public:
         buffer will contain the conversion of the string to the encoding of the
         current locale (and so can fail).
 
-        @param len If non-@NULL, filled with the length of the returned buffer.
+        @param len
+            If non-@NULL, filled with the length of the returned buffer.
+
         @return
             buffer containing the string contents in the specified type,
             notice that it may be @NULL if the conversion failed (e.g. Unicode
@@ -1184,7 +1226,7 @@ public:
     wxString& operator<<(double d);
 
     /**
-        Same as Mid (substring extraction).
+        Same as Mid() (substring extraction).
     */
     wxString operator ()(size_t start, size_t len);
 
@@ -1389,15 +1431,9 @@ public:
 
 };
 
-
 /**
-    FIXME
+    The global wxString instance of an empty string.
-*/
+    Used extensively in the entire wxWidgets API.
-wxString Objects:
-;
-
-/**
-    FIXME
 */
 wxString wxEmptyString;
 
@@ -1407,27 +1443,27 @@ wxString wxEmptyString;
 /**
     @class wxStringBufferLength
 
-    This tiny class allows you to conveniently access the wxString
+    This tiny class allows you to conveniently access the wxString internal buffer
-    internal buffer as a writable pointer without any risk of forgetting to restore
+    as a writable pointer without any risk of forgetting to restore the string to
-    the string to the usable state later, and allows the user to set the internal
+    the usable state later, and allows the user to set the internal length of the string.
-    length of the string.
 
     For example, assuming you have a low-level OS function called
-    @c int GetMeaningOfLifeAsString(char *) copying the value in the provided
+    @c "int GetMeaningOfLifeAsString(char *)" copying the value in the provided
     buffer (which must be writable, of course), and returning the actual length
     of the string, you might call it like this:
 
     @code
-    wxString theAnswer;
+        wxString theAnswer;
         wxStringBuffer theAnswerBuffer(theAnswer, 1024);
         int nLength = GetMeaningOfLifeAsString(theAnswerBuffer);
         theAnswerBuffer.SetLength(nLength);
         if ( theAnswer != "42" )
-        {
             wxLogError("Something is very wrong!");
-        }
     @endcode
 
+    @todo
+        the example above does not make use of wxStringBufferLength??
+
     Note that the exact usage of this depends on whether or not wxUSE_STL is
     enabled. If wxUSE_STL is enabled, wxStringBuffer creates a separate empty
     character buffer, and if wxUSE_STL is disabled, it uses GetWriteBuf() from
@@ -1435,7 +1471,8 @@ wxString wxEmptyString;
     relying on wxStringBuffer containing the old wxString data is not a good
     idea if you want to build your program both with and without wxUSE_STL.
 
-    Note that SetLength @c must be called before wxStringBufferLength destructs.
+    Note that wxStringBuffer::SetLength @b must be called before
+    wxStringBufferLength destructs.
 
     @library{wxbase}
     @category{data}
@@ -1445,8 +1482,9 @@ class wxStringBufferLength
 public:
     /**
         Constructs a writable string buffer object associated with the given string
-        and containing enough space for at least @a len characters. Basically, this
+        and containing enough space for at least @a len characters.
-        is equivalent to calling wxString::GetWriteBuf and
+
+        Basically, this is equivalent to calling wxString::GetWriteBuf and
         saving the result.
     */
     wxStringBufferLength(const wxString& str, size_t len);
@@ -1460,6 +1498,7 @@ public:
     /**
         Sets the internal length of the string referred to by wxStringBufferLength to
         @a nLength characters.
+
         Must be called before wxStringBufferLength destructs.
     */
     void SetLength(size_t nLength);

interface/wx/sysopt.h

@@ -14,7 +14,103 @@
     used to optimize behaviour that doesn't deserve a distinct API,
     but is still important to be able to configure.
 
-    These options are currently recognised by wxWidgets.
+    These options are currently recognised by wxWidgets:
+
+
+    @section sysopt_win Windows
+
+    @beginFlagTable
+    @flag{no-maskblt}
+        1 to never use WIN32's MaskBlt function, 0 to allow it to be used where possible.
+        Default: 0. In some circumstances the MaskBlt function can be slower than using
+        the fallback code, especially if using DC cacheing. By default, MaskBlt will be
+        used where it is implemented by the operating system and driver.
+    @flag{msw.remap}
+        If 1 (the default), wxToolBar bitmap colours will be remapped to the current
+        theme's values. Set this to 0 to disable this functionality, for example if
+        you're using more than 16 colours in your tool bitmaps.
+    @flag{msw.window.no-clip-children}
+        If 1, windows will not automatically get the WS_CLIPCHILDREN style.
+        This restores the way windows are refreshed back to the method used in
+        versions of wxWidgets earlier than 2.5.4, and for some complex window
+        hierarchies it can reduce apparent refresh delays.
+        You may still specify wxCLIP_CHILDREN for individual windows.
+    @flag{msw.notebook.themed-background}
+        If set to 0, globally disables themed backgrounds on notebook pages.
+        Note that this won't disable the theme on the actual notebook background
+        (noticeable only if there are no pages).
+    @flag{msw.staticbox.optimized-paint}
+        If set to 0, switches off optimized wxStaticBox painting.
+        Setting this to 0 causes more flicker, but allows applications to paint
+        graphics on the parent of a static box (the optimized refresh causes any
+        such drawing to disappear).
+    @flag{msw.display.directdraw}
+        If set to 1, use DirectDraw-based implementation of wxDisplay.
+        By default the standard Win32 functions are used.
+    @flag{msw.font.no-proof-quality}
+        If set to 1, use default fonts quality instead of proof quality when
+        creating fonts. With proof quality the fonts have slightly better
+        appearance but not all fonts are available in this quality,
+        e.g. the Terminal font in small sizes is not and this option may be
+        used if wider fonts selection is more important than higher quality.
+    @endFlagTable
+
+
+    @section sysopt_gtk GTK+
+
+    @beginFlagTable
+    @flag{gtk.tlw.can-set-transparent}
+        wxTopLevelWindow::CanSetTransparent() method normally tries to detect
+        automatically whether transparency for top level windows is currently
+        supported, however this may sometimes fail and this option allows to
+        override the automatic detection. Setting it to 1 makes the transparency
+        be always available (setting it can still fail, of course) and setting it
+        to 0 makes it always unavailable.
+    @flag{gtk.desktop}
+        This option can be set to override the default desktop environment
+        determination. Supported values are GNOME and KDE.
+    @flag{gtk.window.force-background-colour}
+        If 1, the backgrounds of windows with the wxBG_STYLE_COLOUR background
+        style are cleared forcibly instead of relying on the underlying GTK+
+        window colour. This works around a display problem when running
+        applications under KDE with the gtk-qt theme installed (0.6 and below).
+    @endFlagTable
+
+
+    @section sysopt_mac Mac
+
+    @beginFlagTable
+    @flag{mac.window-plain-transition}
+        If 1, uses a plainer transition when showing a window.
+        You can also use the symbol wxMAC_WINDOW_PLAIN_TRANSITION.
+    @flag{window-default-variant}
+        The default variant used by windows (cast to integer from the wxWindowVariant enum).
+        Also known as wxWINDOW_DEFAULT_VARIANT.
+    flag{mac.listctrl.always_use_generic}
+        Tells wxListCtrl to use the generic control even when it is capable of
+        using the native control instead. Also knwon as wxMAC_ALWAYS_USE_GENERIC_LISTCTRL.
+    @endFlagTable
+
+
+    @section sysopt_mgl MGL
+
+    @beginFlagTable
+    @flag{mgl.aa-threshold}
+        Set this integer option to point size below which fonts are not antialiased. Default: 10.
+    @flag{mgl.screen-refresh}
+        Screen refresh rate in Hz. A reasonable default is used if not specified.
+    @endFlagTable
+
+
+    @section sysopt_motif Motif
+
+    @beginFlagTable
+    @flag{motif.largebuttons}
+        If 1, uses a bigger default size for wxButtons.
+    @endFlagTable
+
+
+    The compile-time option to include or exclude this functionality is wxUSE_SYSTEM_OPTIONS.
 
     @library{wxbase}
     @category{misc}
@@ -26,41 +122,41 @@ class wxSystemOptions : public wxObject
 {
 public:
     /**
-        Default constructor. You don't need to create an instance of wxSystemOptions
+        Default constructor.
-        since all of its functions are static.
+
+        You don't need to create an instance of wxSystemOptions since all
+        of its functions are static.
     */
     wxSystemOptions();
 
     /**
-        Gets an option. The function is case-insensitive to @e name.
+        Gets an option. The function is case-insensitive to @a name.
         Returns empty string if the option hasn't been set.
 
-        @see SetOption(), GetOptionInt(),
+        @see SetOption(), GetOptionInt(), HasOption()
-             HasOption()
     */
     static wxString GetOption(const wxString& name);
 
     /**
-        Gets an option as an integer. The function is case-insensitive to @e name.
+        Gets an option as an integer. The function is case-insensitive to @a name.
         If the option hasn't been set, this function returns 0.
 
-        @see SetOption(), GetOption(),
+        @see SetOption(), GetOption(), HasOption()
-             HasOption()
     */
     static int GetOptionInt(const wxString& name);
 
     /**
-        Returns @true if the given option is present. The function is
+        Returns @true if the given option is present.
-        case-insensitive to @e name.
+        The function is case-insensitive to @a name.
 
-        @see SetOption(), GetOption(),
+        @see SetOption(), GetOption(), GetOptionInt()
-             GetOptionInt()
     */
     static bool HasOption(const wxString& name);
 
     /**
-        Returns @true if the option with the given @a name had been set to 0
+        Returns @true if the option with the given @a name had been set to 0 value.
-        value. This is mostly useful for boolean options for which you can't use
+
+        This is mostly useful for boolean options for which you can't use
         @c GetOptionInt(name) == 0 as this would also be @true if the option
         hadn't been set at all.
     */
@@ -68,7 +164,7 @@ public:
 
     //@{
     /**
-        Sets an option. The function is case-insensitive to @e name.
+        Sets an option. The function is case-insensitive to @a name.
     */
     void SetOption(const wxString& name, const wxString& value);
     void SetOption(const wxString& name, int value);

interface/wx/textdlg.h

@@ -31,6 +31,8 @@ public:
             Parent window.
         @param message
             Message to show on the dialog.
+        @param caption
+            The caption of the dialog.
         @param defaultValue
             The default value, which may be the empty string.
         @param style