Update docs of backend_manager (#15892)

anntzer · web-flow · commit 782464898711 · 2019-12-13T18:25:31.000+01:00
Update docs of backend_manager
diff --git a/lib/matplotlib/backend_managers.py b/lib/matplotlib/backend_managers.py
@@ -43,11 +43,11 @@ class ToolManager:
 
     Attributes
     ----------
-    figure : `Figure`
-    keypresslock : `widgets.LockDraw`
-        `LockDraw` object to know if the `canvas` key_press_event is locked
-    messagelock : `widgets.LockDraw`
-        `LockDraw` object to know if the message is available to write
+    figure : `.Figure`
+    keypresslock : `~matplotlib.widgets.LockDraw`
+        `.LockDraw` object to know if the `canvas` key_press_event is locked.
+    messagelock : `~matplotlib.widgets.LockDraw`
+        `.LockDraw` object to know if the message is available to write.
     """
 
     def __init__(self, figure=None):
@@ -92,8 +92,8 @@ def set_figure(self, figure, update_tools=True):
         Parameters
         ----------
         figure : `.Figure`
-        update_tools : bool
-            Force tools to update figure
+        update_tools : bool, default: True
+            Force tools to update figure.
         """
         if self._key_press_handler_id:
             self.canvas.mpl_disconnect(self._key_press_handler_id)
@@ -111,23 +111,27 @@ def toolmanager_connect(self, s, func):
 
         Parameters
         ----------
-        s : String
-            Name of the event
-
-            The following events are recognized
+        s : str
+            The name of the event. The following events are recognized:
 
             - 'tool_message_event'
             - 'tool_removed_event'
             - 'tool_added_event'
 
             For every tool added a new event is created
 
-            - 'tool_trigger_TOOLNAME`
-              Where TOOLNAME is the id of the tool.
+            - 'tool_trigger_TOOLNAME', where TOOLNAME is the id of the tool.
+
+        func : callable
+            Callback function for the toolmanager event with signature::
+
+                def func(event: ToolEvent) -> Any
 
-        func : function
-            Function to be called with signature
-            def func(event)
+        Returns
+        -------
+        cid
+            The callback id for the connection. This can be used in
+            `.toolmanager_disconnect`.
         """
         return self._callbacks.connect(s, func)
 
@@ -159,7 +163,7 @@ def active_toggle(self):
 
     def get_tool_keymap(self, name):
         """
-        Get the keymap associated with the specified tool.
+        Return the keymap associated with the specified tool.
 
         Parameters
         ----------
@@ -168,7 +172,8 @@ def get_tool_keymap(self, name):
 
         Returns
         -------
-        list : list of keys associated with the Tool
+        list of str
+            List of keys associated with the tool.
         """
 
         keys = [k for k, i in self._keys.items() if i == name]
@@ -186,7 +191,8 @@ def update_keymap(self, name, *keys):
         ----------
         name : str
             Name of the Tool.
-        keys : keys to associate with the Tool
+        keys : list of str
+            Keys to associate with the tool.
         """
 
         if name not in self._tools:
@@ -208,7 +214,7 @@ def remove_tool(self, name):
         Parameters
         ----------
         name : str
-            Name of the Tool.
+            Name of the tool.
         """
 
         tool = self.get_tool(name)
@@ -294,13 +300,13 @@ def _handle_toggle(self, tool, sender, canvasevent, data):
 
         Parameters
         ----------
-        tool : Tool object
+        tool : `.ToolBase`
         sender : object
-            Object that wishes to trigger the tool
+            Object that wishes to trigger the tool.
         canvasevent : Event
-            Original Canvas event or None
-        data : Object
-            Extra data to pass to the tool when triggering
+            Original Canvas event or None.
+        data : object
+            Extra data to pass to the tool when triggering.
         """
 
         radio_group = tool.radio_group
@@ -358,11 +364,11 @@ def trigger_tool(self, name, sender=None, canvasevent=None, data=None):
         name : str
             Name of the tool.
         sender : object
-            Object that wishes to trigger the tool
+            Object that wishes to trigger the tool.
         canvasevent : Event
-            Original Canvas event or None
-        data : Object
-            Extra data to pass to the tool when triggering
+            Original Canvas event or None.
+        data : object
+            Extra data to pass to the tool when triggering.
         """
         tool = self.get_tool(name)
         if tool is None:
@@ -404,14 +410,22 @@ def tools(self):
 
     def get_tool(self, name, warn=True):
         """
-        Return the tool object, also accepts the actual tool for convenience.
+        Return the tool object with the given name.
+
+        For convenience, this passes tool objects through.
 
         Parameters
         ----------
-        name : str, ToolBase
-            Name of the tool, or the tool itself
-        warn : bool, optional
-            If this method should give warnings.
+        name : str or `.ToolBase`
+            Name of the tool, or the tool itself.
+        warn : bool, default: True
+            Whether a warning should be emitted it no tool with the given name
+            exists.
+
+        Returns
+        -------
+        tool : `.ToolBase` or None
+            The tool or None if no tool with the given name exists.
         """
         if isinstance(name, tools.ToolBase) and name.name in self._tools:
             return name
