Document Artist.get_cursor_data (#12427)

timhoffm · web-flow · commit 4b1e79fbec45 · 2018-10-07T20:41:15.000+02:00
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -1114,13 +1114,46 @@ def matchfunc(x):
 
     def get_cursor_data(self, event):
         """
-        Get the cursor data for a given event.
+        Return the cursor data for a given event.
+
+        .. note::
+            This method is intended to be overridden by artist subclasses
+            (or monkeypatched). As an end-user of Matplotlib you will most
+            likely not call this method yourself.
+
+        Cursor data can be used by Artists to provide additional context
+        information for a given event. The default implementation just returns
+        *None*.
+
+        Subclasses can override the method and return arbitrary data. However,
+        when doing so, they must ensure that `.format_cursor_data` can convert
+        the data to a string representation.
+
+        The only current use case is displaying the z-value of an `.AxesImage`
+        in the status bar of a plot window, while moving the mouse.
+
+        See Also
+        --------
+        format_cursor_data
+
         """
         return None
 
     def format_cursor_data(self, data):
         """
-        Return *cursor data* string formatted.
+        Return a string representation of *data*.
+
+        .. note::
+            This method is intended to be overridden by artist subclasses
+            (or monkeypatched). As an end-user of Matplotlib you will most
+            likely not call this method yourself.
+
+        The default implementation converts ints and floats and arrays of ints
+        and floats into a comma-separated string enclosed in square brackets.
+
+        See Also
+        --------
+        get_cursor_data
         """
         try:
             data[0]
diff --git a/lib/matplotlib/image.py b/lib/matplotlib/image.py
@@ -881,7 +881,14 @@ def get_extent(self):
                 return (-0.5, numcols-0.5, -0.5, numrows-0.5)
 
     def get_cursor_data(self, event):
-        """Get the cursor data for a given event"""
+        """
+        Return the image value at the event position or *None* if the event is
+        outside the image.
+
+        See Also
+        --------
+        matplotlib.artist.Artist.get_cursor_data
+        """
         xmin, xmax, ymin, ymax = self.get_extent()
         if self.origin == 'upper':
             ymin, ymax = ymax, ymin
@@ -1142,7 +1149,7 @@ def set_array(self, *args):
         raise NotImplementedError('Method not supported')
 
     def get_cursor_data(self, event):
-        """Get the cursor data for a given event"""
+        # docstring inherited
         x, y = event.xdata, event.ydata
         if (x < self._Ax[0] or x > self._Ax[-1] or
                 y < self._Ay[0] or y > self._Ay[-1]):
