DOC: update the pandas.Series.set_axis docstring

pandas/core/generic.py

@@ -487,24 +487,37 @@ def _expand_axes(self, key):
 
         return new_axes
 
-    _shared_docs['set_axis'] = """Assign desired index to given axis
+    def set_axis(self, labels, axis=0, inplace=None):
+        """
+        Assign desired index to given axis.
+
+        Indexes for column or row labels can be changed by assigning
+        a list-like or Index.
+
+        .. versionchanged:: 0.21.0
+
+           The signature is now `labels` and `axis`, consistent with
+           the rest of pandas API. Previously, the `axis` and `labels`
+           arguments were respectively the first and second positional
+           arguments.
 
         Parameters
         ----------
-        labels: list-like or Index
-            The values for the new index
-        axis : int or string, default 0
+        labels : list-like, Index
+            The values for the new index.
+
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            The axis to update. The value 0 identifies the rows, and 1
+            identifies the columns.
+
         inplace : boolean, default None
             Whether to return a new %(klass)s instance.
 
-            WARNING: inplace=None currently falls back to to True, but
-            in a future version, will default to False.  Use inplace=True
-            explicitly rather than relying on the default.
+            .. warning::
 
-        .. versionadded:: 0.21.0
-            The signature is make consistent to the rest of the API.
-            Previously, the "axis" and "labels" arguments were respectively
-            the first and second positional arguments.
+               ``inplace=None`` currently falls back to to True, but in a
+               future version, will default to False. Use inplace=True
+               explicitly rather than relying on the default.
 
         Returns
         -------
@@ -513,43 +526,62 @@ def _expand_axes(self, key):
 
         See Also
         --------
-        pandas.NDFrame.rename
+        pandas.DataFrame.rename_axis : Alter the name of the index or columns.
 
         Examples
         --------
+        **Series**
+
         >>> s = pd.Series([1, 2, 3])
         >>> s
         0    1
         1    2
         2    3
         dtype: int64
+
         >>> s.set_axis(['a', 'b', 'c'], axis=0, inplace=False)
         a    1
         b    2
         c    3
         dtype: int64
+
+        The original object is not modified.
+
+        >>> s
+        0    1
+        1    2
+        2    3
+        dtype: int64
+
+        **DataFrame**
+
         >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})
-        >>> df.set_axis(['a', 'b', 'c'], axis=0, inplace=False)
+
+        Change the row labels.
+
+        >>> df.set_axis(['a', 'b', 'c'], axis='index', inplace=False)
            A  B
         a  1  4
         b  2  5
         c  3  6
-        >>> df.set_axis(['I', 'II'], axis=1, inplace=False)
+
+        Change the column labels.
+
+        >>> df.set_axis(['I', 'II'], axis='columns', inplace=False)
            I  II
         0  1   4
         1  2   5
         2  3   6
-        >>> df.set_axis(['i', 'ii'], axis=1, inplace=True)
+
+        Now, update the labels inplace.
+
+        >>> df.set_axis(['i', 'ii'], axis='columns', inplace=True)
         >>> df
            i  ii
         0  1   4
         1  2   5
         2  3   6
-
         """
-
-    @Appender(_shared_docs['set_axis'] % dict(klass='NDFrame'))
-    def set_axis(self, labels, axis=0, inplace=None):
         if is_scalar(labels):
             warnings.warn(
                 'set_axis now takes "labels" as first argument, and '