Separated out function grouping for less confusing parameter docs. (#9651)

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

interface/toolbar.h

@@ -234,38 +234,9 @@ public:
     */
     void AddSeparator();
 
-    //@{
     /**
-        Adds a tool to the toolbar. The first (short and most commonly used)
+        Adds a tool to the toolbar.
-        version has fewer parameters than the full version at the price of not
-        being able to specify some of the more rarely used button features. The
-        last version allows you to add an existing tool.
 
-        @param toolId
-            An integer by which the tool may be identified in subsequent
-            operations.
-        @param kind
-            May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
-            for a checkable tool (such tool stays pressed after it had been
-            toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
-            a radio group of tools each of which is automatically unchecked 
-            whenever another button in the group is checked. ::wxITEM_DROPDOWN
-            specifies that a drop-down menu button will appear next to the
-            tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
-        @param bitmap1
-            The primary tool bitmap.
-        @param bitmap2
-            The bitmap used when the tool is disabled. If it is equal to
-            ::wxNullBitmap, the disabled bitmap is automatically generated by
-            greying the normal one.
-        @param shortHelpString
-            This string is used for the tools tooltip.
-        @param longHelpString
-            This string is shown in the statusbar (if any) of the parent frame
-            when the mouse pointer is inside the tool.
-        @param clientData
-            An optional pointer to client data which can be retrieved later
-            using GetToolClientData().
         @param tool
             The tool to be added.
 
@@ -275,19 +246,86 @@ public:
         @see AddSeparator(), AddCheckTool(), AddRadioTool(),
              InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
     */
-    wxToolBarToolBase* AddTool(int toolId, const wxString& label,
-                               const wxBitmap& bitmap1,
-                               const wxString& shortHelpString = "",
-                               wxItemKind kind = wxITEM_NORMAL);
-    wxToolBarToolBase* AddTool(int toolId, const wxString& label,
-                               const wxBitmap& bitmap1,
-                               const wxBitmap& bitmap2 = wxNullBitmap,
-                               wxItemKind kind = wxITEM_NORMAL,
-                               const wxString& shortHelpString = "",
-                               const wxString& longHelpString = "",
-                               wxObject* clientData = NULL);
     wxToolBarToolBase* AddTool(wxToolBarToolBase* tool);
-    //@}
+
+    /**
+        Adds a tool to the toolbar. This most commonly used version has fewer 
+        parameters than the full version below which specifies the more rarely
+        used button features.
+
+        @param toolId
+            An integer by which the tool may be identified in subsequent
+            operations.
+        @param label        
+            The string to be displayed with the tool.
+        @param bitmap
+            The primary tool bitmap.
+        @param shortHelp
+            This string is used for the tools tooltip.
+        @param kind
+            May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
+            for a checkable tool (such tool stays pressed after it had been
+            toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
+            a radio group of tools each of which is automatically unchecked 
+            whenever another button in the group is checked. ::wxITEM_DROPDOWN
+            specifies that a drop-down menu button will appear next to the
+            tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
+
+        @remarks After you have added tools to a toolbar, you must call
+            Realize() in order to have the tools appear.
+
+        @see AddSeparator(), AddCheckTool(), AddRadioTool(),
+             InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
+    */
+    wxToolBarToolBase* AddTool(int toolId, const wxString& label,
+                               const wxBitmap& bitmap,
+                               const wxString& shortHelp = wxEmptyString,
+                               wxItemKind kind = wxITEM_NORMAL);
+
+    /**
+        Adds a tool to the toolbar.
+
+        @param toolId
+            An integer by which the tool may be identified in subsequent
+            operations.
+        @param label  
+            The string to be displayed with the tool.
+        @param bitmap
+            The primary tool bitmap.
+        @param bmpDisabled
+            The bitmap used when the tool is disabled. If it is equal to
+            ::wxNullBitmap (default), the disabled bitmap is automatically 
+            generated by greying the normal one.
+        @param shortHelpString
+            This string is used for the tools tooltip.
+        @param longHelpString
+            This string is shown in the statusbar (if any) of the parent frame
+            when the mouse pointer is inside the tool.
+        @param kind
+            May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
+            for a checkable tool (such tool stays pressed after it had been
+            toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
+            a radio group of tools each of which is automatically unchecked 
+            whenever another button in the group is checked. ::wxITEM_DROPDOWN
+            specifies that a drop-down menu button will appear next to the
+            tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
+        @param clientData
+            An optional pointer to client data which can be retrieved later
+            using GetToolClientData().
+
+        @remarks After you have added tools to a toolbar, you must call
+            Realize() in order to have the tools appear.
+
+        @see AddSeparator(), AddCheckTool(), AddRadioTool(),
+             InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
+    */
+    wxToolBarToolBase* AddTool(int toolId, const wxString& label,
+                               const wxBitmap& bitmap,
+                               const wxBitmap& bmpDisabled = wxNullBitmap,
+                               wxItemKind kind = wxITEM_NORMAL,
+                               const wxString& shortHelpString = wxEmptyString,
+                               const wxString& longHelpString = wxEmptyString,
+                               wxObject* clientData = NULL);
 
     /**
         Deletes all the tools in the toolbar.
@@ -591,12 +629,9 @@ public:
     */
     bool SetDropdownMenu(int id, wxMenu* menu);
 
-    //@{
     /**
         Set the values to be used as margins for the toolbar.
 
-        @param size
-            Margin size.
         @param x
             Left margin, right margin and inter-tool separation value.
         @param y
@@ -606,11 +641,23 @@ public:
             positioning is to be used, and the default (zero-size) margins are
             to be overridden.
 
+        @see GetMargins()
+    */
+    void SetMargins(int x, int y);
+
+    /**
+        Set the margins for the toolbar.
+
+        @param size
+            Margin size.
+
+        @remarks This must be called before the tools are added if absolute
+            positioning is to be used, and the default (zero-size) margins are
+            to be overridden.
+
         @see GetMargins(), wxSize
     */
     void SetMargins(const wxSize& size);
-    void SetMargins(int x, int y);
-    //@}
 
     /**
         Sets the default size of each tool bitmap. The default bitmap size is 16