From 8f4d0247b56ae157e8486c37e38992015e55ac3e Mon Sep 17 00:00:00 2001
From: Juan Nunez-Iglesias <juan.n@unimelb.edu.au>
Date: Mon, 15 Dec 2014 15:42:54 +1100
Subject: [PATCH] Add docstring to matplotlib imshow plugin

The image is now named as an argument, and the axes are returned, in
keeping with matplotlib convention.
---
 skimage/io/_plugins/matplotlib_plugin.py | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/skimage/io/_plugins/matplotlib_plugin.py b/skimage/io/_plugins/matplotlib_plugin.py
index ec36ce04..4aa0b7f1 100644
--- a/skimage/io/_plugins/matplotlib_plugin.py
+++ b/skimage/io/_plugins/matplotlib_plugin.py
@@ -1,12 +1,27 @@
 import matplotlib.pyplot as plt
 
 
-def imshow(*args, **kwargs):
+def imshow(im, *args, **kwargs):
+    """Show the input image and return the current axes.
+
+    Parameters
+    ----------
+    im : array, shape (M, N[, 3])
+        The image to display.
+
+    *args, **kwargs : positional and keyword arguments
+        These are passed directly to `matplotlib.pyplot.imshow`.
+
+    Returns
+    -------
+    ax : `matplotlib.pyplot.Axes`
+        The axes showing the image.
+    """
     if plt.gca().has_data():
         plt.figure()
     kwargs.setdefault('interpolation', 'nearest')
     kwargs.setdefault('cmap', 'gray')
-    plt.imshow(*args, **kwargs)
+    return plt.imshow(im, *args, **kwargs)
 
 imread = plt.imread
 show = plt.show