DOC: Added warnings about not sharing tickers and autoscaling

madphysicist · madphysicist · commit 54c9995a97d1 · 2016-12-01T18:03:02.000-05:00
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -491,6 +491,15 @@ def __init__(self, fig, rect,
           *yticklabels*      sequence of strings
           *yticks*           sequence of floats
           ================   =========================================
+
+        .. warning::
+
+            Setting `share_tickers` to `False` and changing the
+            `Locator`s of a shared axis may not play with autoscaling.
+            Autoscaling may need to access the `Locator` object of the
+            base axis. Normally, with `share_tickers=True`, the axes
+            are guaranteed to share a `Locator` instance.
+
         """ % {'scale': ' | '.join(
             [repr(x) for x in mscale.get_scale_names()])}
         martist.Artist.__init__(self)
@@ -3926,6 +3935,15 @@ def twinx(self, share_tickers=True):
         .. note::
             For those who are 'picking' artists while using twinx, pick
             events are only called for the artists in the top-most axes.
+
+        .. warning::
+
+            Setting `share_tickers` to `False` and modifying the
+            `Locator` of either axis may cause problems with
+            autoscaling. Autoscaling may require access to the
+            `Locator`, so the behavior will be undefined if the base and
+            twinned axis do not share a `Locator` instance.
+
         """
         ax2 = self._make_twin_axes(sharex=self, share_tickers=share_tickers)
         ax2.yaxis.tick_right()
@@ -3954,6 +3972,15 @@ def twiny(self, share_tickers=True):
         .. note::
             For those who are 'picking' artists while using twiny, pick
             events are only called for the artists in the top-most axes.
+
+        .. warning::
+
+            Setting `share_tickers` to `False` and modifying the
+            `Locator` of either axis may cause problems with
+            autoscaling. Autoscaling may require access to the
+            `Locator`, so the behavior will be undefined if the base and
+            twinned axis do not share a `Locator` instance.
+
         """
 
         ax2 = self._make_twin_axes(sharey=self, share_tickers=share_tickers)
