From 27aebe7ec56b50640f3f4cb98e679e6b0cf0e9f1 Mon Sep 17 00:00:00 2001
From: LindyBalboa <conner.r.phillips.com>
Date: Fri, 2 Sep 2016 17:15:05 +0200
Subject: [PATCH] Clean up SpanSelector documentation

Add reference to AxesWidget.active for disabling the selector.

Resolves #7009
---
 lib/matplotlib/widgets.py | 86 +++++++++++++++++++++------------------
 1 file changed, 47 insertions(+), 39 deletions(-)

diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
index 1c781649c9ac..abd25b61db24 100644
--- a/lib/matplotlib/widgets.py
+++ b/lib/matplotlib/widgets.py
@@ -1679,61 +1679,67 @@ def set_visible(self, visible):
 
 class SpanSelector(_SelectorWidget):
     """
-    Select a min/max range of the x or y axes for a matplotlib Axes.
+    Visually select a min/max range on a single axis and call a function with
+    those values.
 
-    For the selector to remain responsive you must keep a reference to
+    To guarantee that the selector remains responsive, keep a reference to
     it.
 
-    Example usage::
-
-        ax = subplot(111)
-        ax.plot(x,y)
-
-        def onselect(vmin, vmax):
-            print(vmin, vmax)
-        span = SpanSelector(ax, onselect, 'horizontal')
+    In order to turn off the SpanSelector, set `span_selector.active=False`. To
+    turn it back on, set `span_selector.active=True`.
 
-    *onmove_callback* is an optional callback that is called on mouse
-    move within the span range
+    Parameters
+    ----------
+    ax :  :class:`matplotlib.axes.Axes` object
 
-    """
+    onselect : func(min, max), min/max are floats
 
-    def __init__(self, ax, onselect, direction, minspan=None, useblit=False,
-                 rectprops=None, onmove_callback=None, span_stays=False,
-                 button=None):
-        """
-        Create a span selector in *ax*.  When a selection is made, clear
-        the span and call *onselect* with::
+    direction : "horizontal" or "vertical"
+      The axis along which to draw the span selector
 
-            onselect(vmin, vmax)
+    minspan : float, default is None
+     If selection is less than *minspan*, do not call *onselect*
 
-        and clear the span.
+    useblit : bool, default is False
+      If True, use the backend-dependent blitting features for faster
+      canvas updates. Only available for GTKAgg right now.
 
-        *direction* must be 'horizontal' or 'vertical'
+    rectprops : dict, default is None
+      Dictionary of :class:`matplotlib.patches.Patch` properties
 
-        If *minspan* is not *None*, ignore events smaller than *minspan*
+    onmove_callback : func(min, max), min/max are floats, default is None
+      Called on mouse move while the span is being selected
 
-        The span rectangle is drawn with *rectprops*; default::
+    span_stays : bool, default is False
+      If True, the span stays visible after the mouse is released
 
-          rectprops = dict(facecolor='red', alpha=0.5)
+    button : int or list of ints
+      Determines which mouse buttons activate the span selector
+        1 = left mouse button
+        2 = center mouse button (scroll wheel)
+        3 = right mouse button
 
-        Set the visible attribute to *False* if you want to turn off
-        the functionality of the span selector
+    Examples
+    --------
+    >>> import matplotlib.pyplot as plt
+    >>> import matplotlib.widgets as mwidgets
+    >>> fig, ax = plt.subplots()
+    >>> ax.plot([1, 2, 3], [10, 50, 100])
+    >>> def onselect(vmin, vmax):
+            print(vmin, vmax)
+    >>> rectprops = dict(facecolor='blue', alpha=0.5)
+    >>> span = mwidgets.SpanSelector(ax, onselect, 'horizontal',
+                                     rectprops=rectprops)
+    >>> fig.show()
 
-        If *span_stays* is True, the span stays visble after making
-        a valid selection.
+    See also: :ref:`widgets-span_selector`
 
-        *button* is a list of integers indicating which mouse buttons should
-        be used for selection.  You can also specify a single
-        integer if only a single button is desired.  Default is *None*,
-        which does not limit which button can be used.
+    """
 
-        Note, typically:
-         1 = left mouse button
-         2 = center mouse button (scroll wheel)
-         3 = right mouse button
+    def __init__(self, ax, onselect, direction, minspan=None, useblit=False,
+                 rectprops=None, onmove_callback=None, span_stays=False,
+                 button=None):
 
-        """
         _SelectorWidget.__init__(self, ax, onselect, useblit=useblit,
                                  button=button)
 
@@ -1763,6 +1769,7 @@ def __init__(self, ax, onselect, direction, minspan=None, useblit=False,
         self.new_axes(ax)
 
     def new_axes(self, ax):
+        """Set SpanSelector to operate on a new Axes"""
         self.ax = ax
         if self.canvas is not ax.figure.canvas:
             if self.canvas is not None:
@@ -2479,7 +2486,8 @@ def onselect(verts):
 
     def __init__(self, ax, onselect=None, useblit=True, lineprops=None,
             button=None):
-        _SelectorWidget.__init__(self, ax, onselect, useblit=useblit, button=button)
+        _SelectorWidget.__init__(self, ax, onselect, useblit=useblit,
+            button=button)
 
         self.verts = None