@@ -3395,11 +3395,17 @@ def trigger_tool(self, name):
33953395
33963396def add_toolitem (self ,name ,group ,position ,image ,description ,toggle ):
33973397"""
3398- Add a toolitem to the container.
3398+ A hook to add a toolitem to the container.
33993399
3400- This method must be implemented per backend.
3400+ This hook must be implemented in each backend and contains the
3401+ backend-specific code to add an element to the toolbar.
34013402
3402- The callback associated with the button click event,
3403+ .. warning::
3404+ This is part of the backend implementation and should
3405+ not be called by end-users. They should instead call
3406+ `.ToolContainerBase.add_tool`.
3407+
3408+ The callback associated with the button click event
34033409 must be *exactly* ``self.trigger_tool(name)``.
34043410
34053411 Parameters
@@ -3425,7 +3431,16 @@ def add_toolitem(self, name, group, position, image, description, toggle):
34253431
34263432def toggle_toolitem (self ,name ,toggled ):
34273433"""
3428- Toggle the toolitem without firing event.
3434+ A hook to toggle a toolitem without firing an event.
3435+
3436+ This hook must be implemented in each backend and contains the
3437+ backend-specific code to silently toggle a toolbar element.
3438+
3439+ .. warning::
3440+ This is part of the backend implementation and should
3441+ not be called by end-users. They should instead call
3442+ `.ToolManager.trigger_tool` or `.ToolContainerBase.trigger_tool`
3443+ (which are equivalent).
34293444
34303445 Parameters
34313446 ----------
@@ -3438,11 +3453,16 @@ def toggle_toolitem(self, name, toggled):
34383453
34393454def remove_toolitem (self ,name ):
34403455"""
3441- Remove a toolitem from the`ToolContainer` .
3456+ A hook to remove a toolitem from thecontainer .
34423457
3443- This method must get implemented per backend.
3458+ This hook must be implemented in each backend and contains the
3459+ backend-specific code to remove an element from the toolbar; it is
3460+ called when `.ToolManager` emits a `tool_removed_event`.
34443461
3445- Called when `.ToolManager` emits a `tool_removed_event`.
3462+ .. warning::
3463+ This is part of the backend implementation and should
3464+ not be called by end-users. They should instead call
3465+ `.ToolManager.remove_tool`.
34463466
34473467 Parameters
34483468 ----------