DOC: update DataFrame.xs docstring and add examples

pandas/core/frame.py

@@ -1831,21 +1831,71 @@ def _series(self):
 
     def xs(self, key, axis=0, level=None, copy=True):
         """
-        Returns a cross-section (row or column) from the DataFrame as a Series
-        object. Defaults to returning a row (axis 0)
+        Returns a cross-section (row(s) or column(s)) from the DataFrame.
+        Defaults to cross-section on the rows (axis=0).
 
         Parameters
         ----------
         key : object
             Some label contained in the index, or partially in a MultiIndex
         axis : int, default 0
             Axis to retrieve cross-section on
+        level : object, defaults to first n levels (n=1 or len(key))
+            In case of a key partially contained in a MultiIndex, indicate
+            which levels are used. Levels can be referred by label or position.
         copy : boolean, default True
             Whether to make a copy of the data
 
+        Examples
+        --------
+        >>> df
+           A  B  C
+        a  4  5  2
+        b  4  0  9
+        c  9  7  3
+        >>> df.xs('a')
+        A    4
+        B    5
+        C    2
+        Name: a
+        >>> df.xs('C', axis=1)
+        a    2
+        b    9
+        c    3
+        Name: C
+        >>> s = df.xs('a', copy=False)
+        >>> s['A'] = 100
+        >>> df
+             A  B  C
+        a  100  5  2
+        b    4  0  9
+        c    9  7  3
+
+
+        >>> df
+                            A  B  C  D
+        first second third
+        bar   one    1      4  1  8  9
+              two    1      7  5  5  0
+        baz   one    1      6  6  8  0
+              three  2      5  3  5  3
+        >>> df.xs(('baz', 'three'))
+               A  B  C  D
+        third
+        2      5  3  5  3
+        >>> df.xs('one', level=1)
+                     A  B  C  D
+        first third
+        bar   1      4  1  8  9
+        baz   1      6  6  8  0
+        >>> df.xs(('baz', 2), level=[0, 'third'])
+                A  B  C  D
+        second
+        three   5  3  5  3
+
         Returns
         -------
-        xs : Series
+        xs : Series or DataFrame
         """
         labels = self._get_axis(axis)
         if level is not None: