Merge branch 'im/docadditions' of https://github.com/imciner2/wxWidgets

Various documentation fixes and improvements.

See https://github.com/wxWidgets/wxWidgets/pull/2047

interface/wx/aui/auibar.h

@@ -259,15 +259,22 @@ public:
 
     /**
       Returns the toolbar item kind.
+
+      @return one of @c wxITEM_NORMAL, @c wxITEM_CHECK or @c wxITEM_RADIO,
+      @c wxITEM_SEPARATOR, @c wxITEM_CONTROL, @c wxITEM_SPACER, @c wxITEM_LABEL,
     */
     int GetKind() const;
 
     /**
+      Set the current state of the toolbar item.
 
+      @param new_state is an or'd combination of flags from wxAuiPaneButtonState
     */
     void SetState(int new_state);
     /**
+      Gets the current state of the toolbar item.
 
+      @return an or'd combination of flags from wxAuiPaneButtonState representing the current state
     */
     int GetState() const;
 
@@ -610,26 +617,34 @@ public:
 
     @beginStyleTable
     @style{wxAUI_TB_TEXT}
+        Display the label strings on the toolbar buttons.
     @style{wxAUI_TB_NO_TOOLTIPS}
+        Do not show tooltips for the toolbar items.
     @style{wxAUI_TB_NO_AUTORESIZE}
+        Do not automatically resize the toolbar when new tools are added.
     @style{wxAUI_TB_GRIPPER}
+        Show the toolbar's gripper control. If the toolbar is added to
+        an AUI pane that contains a gripper, this style will be automatically
+        set.
     @style{wxAUI_TB_OVERFLOW}
+        Show an overflow menu containing toolbar items that can't fit on the
+        toolbar if it is too small.
     @style{wxAUI_TB_VERTICAL}
-        using this style forces the toolbar to be vertical and
+        Using this style forces the toolbar to be vertical and
         be only dockable to the left or right sides of the window
         whereas by default it can be horizontal or vertical and
-        be docked anywhere
+        be docked anywhere.
     @style{wxAUI_TB_HORZ_LAYOUT}
     @style{wxAUI_TB_HORIZONTAL}
-        analogous to wxAUI_TB_VERTICAL, but forces the toolbar
+        Analogous to wxAUI_TB_VERTICAL, but forces the toolbar
-        to be horizontal
+        to be horizontal.
     @style{wxAUI_TB_PLAIN_BACKGROUND}
         Draw a plain background (based on parent) instead of the
         default gradient background.
     @style{wxAUI_TB_HORZ_TEXT}
         Equivalent to wxAUI_TB_HORZ_LAYOUT | wxAUI_TB_TEXT
     @style{wxAUI_TB_DEFAULT_STYLE}
-        The default is to have no styles
+        The default is to have no styles.
     @endStyleTable
 
     @beginEventEmissionTable{wxAuiToolBarEvent}
@@ -854,6 +869,18 @@ public:
     wxString GetToolLongHelp(int toolId) const;
     void SetToolLongHelp(int toolId, const wxString& help_string);
 
+    /**
+      Add toolbar items that are always displayed in the overflow menu.
+
+      If there are custom items set, then the overflow menu will be
+      displayed even if there are no items from the main toolbar that
+      overflow.
+
+      @param prepend are the items to show before any overflow items
+      @param append are the items to show after any overflow items
+
+      @note The toolbar must have the @c wxAUI_TB_OVERFLOW style.
+     */
     void SetCustomOverflowItems(const wxAuiToolBarItemArray& prepend,
                                 const wxAuiToolBarItemArray& append);
 

interface/wx/filedlg.h

@@ -133,6 +133,7 @@ const char wxFileSelectorDefaultWildcardStr[];
     @style{wxFD_OVERWRITE_PROMPT}
            For save dialog only: prompt for a confirmation if a file will be
            overwritten.
+           This style is always enabled on wxOSX and cannot be disabled.
     @style{wxFD_NO_FOLLOW}
            Directs the dialog to return the path and file name of the selected
            shortcut file, not its target as it does by default. Currently this

interface/wx/toolbar.h

@@ -221,8 +221,7 @@ public:
     @style{wxTB_RIGHT}
         Align the toolbar at the right side of parent window.
     @style{wxTB_DEFAULT_STYLE}
-        Combination of @c wxTB_HORIZONTAL and @c wxTB_FLAT. This style is new
+        The @c wxTB_HORIZONTAL style. This style is new since wxWidgets 2.9.5.
-        since wxWidgets 2.9.5.
     @endStyleTable
 
     See also @ref overview_windowstyles. Note that the wxMSW native toolbar