Make function signatures more explicit

Author: timhoffm

lib/matplotlib/__init__.py

@@ -1147,7 +1147,7 @@ def rc_params_from_file(fname, fail_on_error=False, use_default_template=True):
 
 def rc(group, **kwargs):
     """
-    Set the current rc params.  Group is the grouping for the rc, e.g.,
+    Set the current rc params.  *group* is the grouping for the rc, e.g.,
     for ``lines.linewidth`` the group is ``lines``, for
     ``axes.facecolor``, the group is ``axes``, and so on.  Group may
     also be a list or tuple of group names, e.g., (*xtick*, *ytick*).

lib/matplotlib/axes/_axes.py

@@ -471,8 +471,8 @@ def text(self, x, y, s, fontdict=None, withdash=False, **kwargs):
         return t
 
     @docstring.dedent_interpd
-    def annotate(self, *args, **kwargs):
-        a = mtext.Annotation(*args, **kwargs)
+    def annotate(self, text, xy, *args, **kwargs):
+        a = mtext.Annotation(text, xy, *args, **kwargs)
         a.set_transform(mtransforms.IdentityTransform())
         if 'clip_on' in kwargs:
             a.set_clip_path(self.patch)
@@ -4668,8 +4668,8 @@ def arrow(self, x, y, dx, dy, **kwargs):
         self.add_artist(a)
         return a
 
-    def quiverkey(self, *args, **kw):
-        qk = mquiver.QuiverKey(*args, **kw)
+    def quiverkey(self, Q, X, Y, U, label, **kw):
+        qk = mquiver.QuiverKey(Q, X, Y, U, label, **kw)
         self.add_artist(qk)
         return qk
     quiverkey.__doc__ = mquiver.QuiverKey.quiverkey_doc

lib/matplotlib/figure.py

@@ -1939,18 +1939,14 @@ def colorbar(self, mappable, cax=None, ax=None, use_gridspec=True, **kw):
         self.stale = True
         return cb
 
-    def subplots_adjust(self, *args, **kwargs):
+    def subplots_adjust(self, left=None, bottom=None, right=None, top=None,
+                        wspace=None, hspace=None):
         """
-        Call signature::
-
-          subplots_adjust(left=None, bottom=None, right=None, top=None,
-                          wspace=None, hspace=None)
-
         Update the :class:`SubplotParams` with *kwargs* (defaulting to rc when
         *None*) and update the subplot locations.
 
         """
-        self.subplotpars.update(*args, **kwargs)
+        self.subplotpars.update(left, bottom, right, top, wspace, hspace)
         for ax in self.axes:
             if not isinstance(ax, SubplotBase):
                 # Check if sharing a subplots axis

lib/matplotlib/pyplot.py

@@ -294,8 +294,8 @@ def pause(interval):
 
 
 @docstring.copy_dedent(matplotlib.rc)
-def rc(*args, **kwargs):
-    matplotlib.rc(*args, **kwargs)
+def rc(group, **kwargs):
+    matplotlib.rc(group, **kwargs)
 
 
 @docstring.copy_dedent(matplotlib.rc_context)
@@ -344,8 +344,8 @@ def sci(im):
 ## Any Artist ##
 # (getp is simply imported)
 @docstring.copy(_setp)
-def setp(*args, **kwargs):
-    return _setp(*args, **kwargs)
+def setp(obj, *args, **kwargs):
+    return _setp(obj, *args, **kwargs)
 
 
 def xkcd(scale=1, length=100, randomness=2):
@@ -735,13 +735,13 @@ def waitforbuttonpress(*args, **kwargs):
 # Putting things in figures
 
 @docstring.copy_dedent(Figure.text)
-def figtext(*args, **kwargs):
-    return gcf().text(*args, **kwargs)
+def figtext(x, y, s, *args, **kwargs):
+    return gcf().text(x, y, s, *args, **kwargs)
 
 
 @docstring.copy_dedent(Figure.suptitle)
-def suptitle(*args, **kwargs):
-    return gcf().suptitle(*args, **kwargs)
+def suptitle(t, **kwargs):
+    return gcf().suptitle(t, **kwargs)
 
 
 @docstring.copy_dedent(Figure.figimage)
@@ -1289,15 +1289,11 @@ def twiny(ax=None):
     return ax1
 
 
-def subplots_adjust(*args, **kwargs):
+def subplots_adjust(left=None, bottom=None, right=None, top=None,
+                    wspace=None, hspace=None):
     """
     Tune the subplot layout.
 
-    call signature::
-
-      subplots_adjust(left=None, bottom=None, right=None, top=None,
-                      wspace=None, hspace=None)
-
     The parameter meanings (and suggested defaults) are::
 
       left  = 0.125  # the left side of the subplots of the figure
@@ -1312,7 +1308,7 @@ def subplots_adjust(*args, **kwargs):
     The actual defaults are controlled by the rc file
     """
     fig = gcf()
-    fig.subplots_adjust(*args, **kwargs)
+    fig.subplots_adjust(left, bottom, right, top, wspace, hspace)
 
 
 def subplot_tool(targetfig=None):
@@ -1597,14 +1593,10 @@ def ylim(*args, **kwargs):
 
 
 @docstring.dedent_interpd
-def xscale(*args, **kwargs):
+def xscale(scale, **kwargs):
     """
     Set the scaling of the x-axis.
 
-    Call signature::
-
-        xscale(scale, **kwargs)
-
     Parameters
     ----------
     scale : [%(scale)s]
@@ -1621,18 +1613,14 @@ def xscale(*args, **kwargs):
 
     %(scale_docs)s
     """
-    gca().set_xscale(*args, **kwargs)
+    gca().set_xscale(scale, **kwargs)
 
 
 @docstring.dedent_interpd
-def yscale(*args, **kwargs):
+def yscale(scale, **kwargs):
     """
     Set the scaling of the y-axis.
 
-    Call signature::
-
-        yscale(scale, **kwargs)
-
     Parameters
     ----------
     scale : [%(scale)s]
@@ -1649,7 +1637,7 @@ def yscale(*args, **kwargs):
 
     %(scale_docs)s
     """
-    gca().set_yscale(*args, **kwargs)
+    gca().set_yscale(scale, **kwargs)
 
 
 def xticks(*args, **kwargs):
@@ -2316,13 +2304,13 @@ def set_cmap(cmap):
 
 
 @docstring.copy_dedent(_imread)
-def imread(*args, **kwargs):
-    return _imread(*args, **kwargs)
+def imread(fname, format=None):
+    return _imread(fname, format)
 
 
 @docstring.copy_dedent(_imsave)
-def imsave(*args, **kwargs):
-    return _imsave(*args, **kwargs)
+def imsave(fname, arr, **kwargs):
+    return _imsave(fname, arr, **kwargs)
 
 
 def matshow(A, fignum=None, **kw):