Clarify public-ness of some ToolContainerBase APIs.

add_toolitem is clearly intended as a helper for add_tool (add_tool sets
up a bunch of auxiliary arguments for it which the end-user should not
bother with).  toggle_toolitem and remove_toolitem also look
internal-ish.  Document them as such.

Author: anntzer

lib/matplotlib/backend_bases.py

@@ -3388,11 +3388,17 @@ def trigger_tool(self, name):
 
     def add_toolitem(self, name, group, position, image, description, toggle):
         """
-        Add a toolitem to the container.
+        A hook to add a toolitem to the container.
 
-        This method must be implemented per backend.
+        This hook must be implemented in each backend and contains the
+        backend-specific code to add an element to the toolbar.
 
-        The callback associated with the button click event,
+        .. warning::
+            This is part of the backend implementation and should
+            not be called by end-users.  They should instead call
+            `.ToolContainerBase.add_tool`.
+
+        The callback associated with the button click event
         must be *exactly* ``self.trigger_tool(name)``.
 
         Parameters
@@ -3418,7 +3424,16 @@ def add_toolitem(self, name, group, position, image, description, toggle):
 
     def toggle_toolitem(self, name, toggled):
         """
-        Toggle the toolitem without firing event.
+        A hook to toggle a toolitem without firing an event.
+
+        This hook must be implemented in each backend and contains the
+        backend-specific code to silently toggle a toolbar element.
+
+        .. warning::
+            This is part of the backend implementation and should
+            not be called by end-users.  They should instead call
+            `.ToolManager.trigger_tool` or `.ToolContainerBase.trigger_tool`
+            (which are equivalent).
 
         Parameters
         ----------
@@ -3431,11 +3446,16 @@ def toggle_toolitem(self, name, toggled):
 
     def remove_toolitem(self, name):
         """
-        Remove a toolitem from the `ToolContainer`.
+        A hook to remove a toolitem from the container.
 
-        This method must get implemented per backend.
+        This hook must be implemented in each backend and contains the
+        backend-specific code to remove an element from the toolbar; it is
+        called when `.ToolManager` emits a `tool_removed_event`.
 
-        Called when `.ToolManager` emits a `tool_removed_event`.
+        .. warning::
+            This is part of the backend implementation and should
+            not be called by end-users.  They should instead call
+            `.ToolManager.remove_tool`.
 
         Parameters
         ----------