Clarify public-ness of some ToolContainerBase APIs.

anntzer · anntzer · commit fd9088168b66 · 2024-05-04T13:16:12.000+02:00
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.
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -3413,6 +3413,12 @@ def add_toolitem(self, name, group, position, image, description, toggle):
               state between consecutive clicks).
             * `False` : The button is a normal button (returns to unpressed
               state after release).
+
+        Note
+        ----
+        This method is not intended to be called by end-users (who should
+        instead `.ToolContainerBase.add_tool`); it is provided to be
+        implemented by third-party backends.
         """
         raise NotImplementedError
 
@@ -3426,6 +3432,13 @@ def toggle_toolitem(self, name, toggled):
             Id of the tool to toggle.
         toggled : bool
             Whether to set this tool as toggled or not.
+
+        Note
+        ----
+        This method is not intended to be called by end-users
+        (who should instead use `.ToolManager.trigger_tool` or
+        `.ToolContainerBase.trigger_tool`, which are equivalent); it is
+        provided to be implemented by third-party backends.
         """
         raise NotImplementedError
 
@@ -3441,6 +3454,12 @@ def remove_toolitem(self, name):
         ----------
         name : str
             Name of the tool to remove.
+
+        Note
+        ----
+        This method is not intended to be called by end-users (who should
+        instead use `.ToolManager.remove_tool`); it is provided to be
+        implemented by third-party backends.
         """
         raise NotImplementedError
 
