DOC: update the Series.reset_index DocString

pandas/core/series.py

@@ -1002,36 +1002,88 @@ def _set_value(self, label, value, takeable=False):
 
     def reset_index(self, level=None, drop=False, name=None, inplace=False):
         """
-        Analogous to the :meth:`pandas.DataFrame.reset_index` function, see
-        docstring there.
+        Generate a new DataFrame with columns containing the data and 
+        the index of the original Series, or, if drop is True, 
+        a Series with numeric index.
+
+        For an Index Series, the results is a two-column DataFrame with 
+        index tourned in column.
+        For a MultiIndex Series, the results is a multi-column 
+        DataFrame with each level being turned into a column.
+        The new columns will be named level_n (with n increasing frm 0) 
+        if the name is None. 
 
         Parameters
         ----------
         level : int, str, tuple, or list, default None
             Only remove the given levels from the index. Removes all levels by
-            default
-        drop : boolean, default False
-            Do not try to insert index into dataframe columns
+            default.
+        drop : bool, default False
+            Do not try to insert index into dataframe columns.
         name : object, default None
-            The name of the column corresponding to the Series values
-        inplace : boolean, default False
-            Modify the Series in place (do not create a new object)
+            The name of the column corresponding to the Series values.
+        inplace : `bool`, default False
+            Modify the Series in place (do not create a new object).
 
         Returns
         ----------
-        resetted : DataFrame, or Series if drop == True
+        reset : DataFrame, or Series if drop == True
+
+        See Also
+        --------
+        pandas.DataFrame.reset_index: Analogous function for DataFrame
 
         Examples
         --------
+
+        Generate a pandas.Series.
+
         >>> s = pd.Series([1, 2, 3, 4], index=pd.Index(['a', 'b', 'c', 'd'],
         ...                                            name = 'idx'))
+
+        To generate a pandas.DataFrame with default index, 
+        call the reset_index() method.
+
         >>> s.reset_index()
           idx  0
         0   a  1
         1   b  2
         2   c  3
         3   d  4
 
+        To specify the name of the column corrisponding
+        to the Series values, use the name parameter.
+
+        >>> s.reset_index(name='values')
+          idx  values
+        0   a       1
+        1   b       2
+        2   c       3
+        3   d       4
+
+        To generate a new pandas.Series with the default
+        index, set the drop parameter to True.
+
+        >>> s.reset_index(drop=True)
+        0    1
+        1    2
+        2    3
+        3    4
+        dtype: int64
+
+        To update the Series in place, without generating a new one
+        set inplace to True. Note that it also requires drop=True.
+
+        >>> s.reset_index(inplace=True, drop=True)
+        >>> s
+        0    1
+        1    2
+        2    3
+        3    4
+        dtype: int64
+
+        Generate a MultiIndex Series.
+
         >>> arrays = [np.array(['bar', 'bar', 'baz', 'baz', 'foo',
         ...                     'foo', 'qux', 'qux']),
         ...           np.array(['one', 'two', 'one', 'two', 'one', 'two',
@@ -1040,6 +1092,10 @@ def reset_index(self, level=None, drop=False, name=None, inplace=False):
         ...     range(8),
         ...     index=pd.MultiIndex.from_arrays(arrays,
         ...                                     names=['a', 'b']))
+
+        To remove a specific level from the Index, use the 
+        level parameter.
+
         >>> s2.reset_index(level='a')
                a  0
         b
@@ -1051,7 +1107,23 @@ def reset_index(self, level=None, drop=False, name=None, inplace=False):
         two  foo  5
         one  qux  6
         two  qux  7
+
+        If level parameter is not set, all levels are removed
+        from the Index.
+
+        >>> s2.reset_index()
+             a    b  0
+        0  bar  one  0
+        1  bar  two  1
+        2  baz  one  2
+        3  baz  two  3
+        4  foo  one  4
+        5  foo  two  5
+        6  qux  one  6
+        7  qux  two  7
         """
+
+
         inplace = validate_bool_kwarg(inplace, 'inplace')
         if drop:
             new_index = com._default_index(len(self))