Repository: matplotlib/matplotlib
Pull request: Add note about hist2d resetting axis limits
Maybe fixes #3815? I've also added a couple of other bits of markup to make the docstring nicer in general.

Problem statement:
hist2d and x/y limits
The hist2d doesn't behave as expected (at least as I expected) when setting x and y limits.

``` python

x = randn(10000);
y = randn(10000);


figure()
xlim(-2, 2);
hist(x, bins=100); # obeys the xlim

figure();
xlim(-2, 2);
ylim(-2, 2);
hist2d(x, y, bins=100); # sets it's own xlim that seems to depend on bin size
```

Running matplotlib 1.4.2

Hints from issue discussion:
hist2D should probably respect the same auto-scaling rules as (some of) the other plotting methods.  Bit worried we won't be able to do this without breaking API..

The source of the problem is hard-coded calls to `ax.set_{x,y}lim` at lines 5994 in `axes/_axes.py`

At a minimum this behavior should be documented, even if it is not changed.

Are we aware of any other places where this occurs? Happy to open another issue to document the behavior for these while this one sits.
Just a note that this is still an issue on the current master branch.

Commit message: Add note about hist2d resetting axis limits

Patch to review:
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
index 1e1b4347bb22..3f41f4ea8f3a 100644
--- a/lib/matplotlib/axes/_axes.py
+++ b/lib/matplotlib/axes/_axes.py
@@ -6462,21 +6462,21 @@ def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None,
                 - If int, the number of bins for the two dimensions
                   (nx=ny=bins).
 
-                - If [int, int], the number of bins in each dimension
+                - If ``[int, int]``, the number of bins in each dimension
                   (nx, ny = bins).
 
                 - If array_like, the bin edges for the two dimensions
                   (x_edges=y_edges=bins).
 
-                - If [array, array], the bin edges in each dimension
+                - If ``[array, array]``, the bin edges in each dimension
                   (x_edges, y_edges = bins).
 
             The default value is 10.
 
         range : array_like shape(2, 2), optional, default: None
              The leftmost and rightmost edges of the bins along each dimension
-             (if not specified explicitly in the bins parameters): [[xmin,
-             xmax], [ymin, ymax]]. All values outside of this range will be
+             (if not specified explicitly in the bins parameters): ``[[xmin,
+             xmax], [ymin, ymax]]``. All values outside of this range will be
              considered outliers and not tallied in the histogram.
 
         normed : bool, optional, default: False
@@ -6510,31 +6510,33 @@ def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None,
         Other Parameters
         ----------------
         cmap : Colormap or str, optional
-            A :class:`matplotlib.colors.Colormap` instance.  If not set, use rc
+            A :class:`.colors.Colormap` instance.  If not set, use rc
             settings.
 
         norm : Normalize, optional
-            A :class:`matplotlib.colors.Normalize` instance is used to
+            A :class:`.colors.Normalize` instance is used to
             scale luminance data to ``[0, 1]``. If not set, defaults to
-            ``Normalize()``.
+            :class:`.colors.Normalize()`.
 
         vmin/vmax : None or scalar, optional
-            Arguments passed to the `Normalize` instance.
+            Arguments passed to the :class:`~.colors.Normalize` instance.
 
         alpha : ``0 <= scalar <= 1`` or ``None``, optional
             The alpha blending value.
 
         See also
         --------
-        hist : 1D histogram
+        hist : 1D histogram plotting
 
         Notes
         -----
-        Rendering the histogram with a logarithmic color scale is
-        accomplished by passing a :class:`colors.LogNorm` instance to
-        the *norm* keyword argument. Likewise, power-law normalization
-        (similar in effect to gamma correction) can be accomplished with
-        :class:`colors.PowerNorm`.
+        - Currently ``hist2d`` calculates it's own axis limits, and any limits
+          previously set are ignored.
+        - Rendering the histogram with a logarithmic color scale is
+          accomplished by passing a :class:`.colors.LogNorm` instance to
+          the *norm* keyword argument. Likewise, power-law normalization
+          (similar in effect to gamma correction) can be accomplished with
+          :class:`.colors.PowerNorm`.
         """
 
         h, xedges, yedges = np.histogram2d(x, y, bins=bins, range=range,


Code review comments:
diff_hunk: @@ -6510,31 +6510,33 @@ def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None,
         Other Parameters
         ----------------
         cmap : Colormap or str, optional
-            A :class:`matplotlib.colors.Colormap` instance.  If not set, use rc
+            A :class:`.colors.Colormap` instance.  If not set, use rc
path: lib/matplotlib/axes/_axes.py
text: @user1:
Since we are using 'obj' as the default role, `:class:` should now be left out for improved readability.