Merge pull request matplotlib#18686 from anntzer/setp

Numpydocify setp.

Author: brunobeltran

lib/matplotlib/artist.py

@@ -1558,7 +1558,7 @@ def pprint_getters(self):
 
 def getp(obj, property=None):
     """
-    Return the value of an object's *property*, or print all of them.
+    Return the value of an `.Artist`'s *property*, or print all of them.
 
     Parameters
     ----------
@@ -1579,6 +1579,10 @@ def getp(obj, property=None):
         e.g.:
 
           linewidth or lw = 2
+
+    See Also
+    --------
+    setp
     """
     if property is None:
         insp = ArtistInspector(obj)
@@ -1593,52 +1597,61 @@ def getp(obj, property=None):
 
 def setp(obj, *args, file=None, **kwargs):
     """
-    Set a property on an artist object.
+    Set one or more properties on an `.Artist`, or list allowed values.
+
+    Parameters
+    ----------
+    obj : `.Artist` or list of `.Artist`
+        The artist(s) whose properties are being set or queried.  When setting
+        properties, all artists are affected; when querying the allowed values,
+        only the first instance in the sequence is queried.
 
-    matplotlib supports the use of :func:`setp` ("set property") and
-    :func:`getp` to set and get object properties, as well as to do
-    introspection on the object.  For example, to set the linestyle of a
-    line to be dashed, you can do::
+        For example, two lines can be made thicker and red with a single call:
 
-      >>> line, = plot([1, 2, 3])
-      >>> setp(line, linestyle='--')
+        >>> x = arange(0, 1, 0.01)
+        >>> lines = plot(x, sin(2*pi*x), x, sin(4*pi*x))
+        >>> setp(lines, linewidth=2, color='r')
 
-    If you want to know the valid types of arguments, you can provide
-    the name of the property you want to set without a value::
+    file : file-like, default: `sys.stdout`
+        Where `setp` writes its output when asked to list allowed values.
 
-      >>> setp(line, 'linestyle')
-          linestyle: {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
+        >>> with open('output.log') as file:
+        ...     setp(line, file=file)
+
+        The default, ``None``, means `sys.stdout`.
 
-    If you want to see all the properties that can be set, and their
-    possible values, you can do::
+    *args, **kwargs
+        The properties to set.  The following combinations are supported:
 
-      >>> setp(line)
-          ... long output listing omitted
+        - Set the linestyle of a line to be dashed:
 
-    By default `setp` prints to `sys.stdout`, but this can be modified using
-    the *file* keyword-only argument::
+          >>> line, = plot([1, 2, 3])
+          >>> setp(line, linestyle='--')
+
+        - Set multiple properties at once:
+
+          >>> setp(line, linewidth=2, color='r')
+
+        - List allowed values for a line's linestyle:
+
+          >>> setp(line, 'linestyle')
+          linestyle: {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
 
-      >>> with fopen('output.log') as f:
-      >>>     setp(line, file=f)
+        - List all properties that can be set, and their allowed values:
 
-    :func:`setp` operates on a single instance or a iterable of
-    instances. If you are in query mode introspecting the possible
-    values, only the first instance in the sequence is used. When
-    actually setting values, all the instances will be set.  e.g.,
-    suppose you have a list of two lines, the following will make both
-    lines thicker and red::
+          >>> setp(line)
+          agg_filter: a filter function, ...
+          [long output listing omitted]
 
-      >>> x = arange(0, 1, 0.01)
-      >>> y1 = sin(2*pi*x)
-      >>> y2 = sin(4*pi*x)
-      >>> lines = plot(x, y1, x, y2)
-      >>> setp(lines, linewidth=2, color='r')
+        `setp` also supports MATLAB style string/value pairs.  For example, the
+        following are equivalent:
 
-    :func:`setp` works with the MATLAB style string/value pairs or
-    with python kwargs.  For example, the following are equivalent::
+        >>> setp(lines, 'linewidth', 2, 'color', 'r')  # MATLAB style
+        >>> setp(lines, linewidth=2, color='r')        # Python style
 
-      >>> setp(lines, 'linewidth', 2, 'color', 'r')  # MATLAB style
-      >>> setp(lines, linewidth=2, color='r')        # python style
+    See Also
+    --------
+    getp
     """
 
     if isinstance(obj, Artist):