DOC: update the pandas.DataFrame.pct_change docstring

pandas/core/generic.py

@@ -7515,29 +7515,91 @@ def _check_percentile(self, q):
         return q
 
     _shared_docs['pct_change'] = """
-        Percent change over given number of periods.
+        Percentage change between the current and previous element.
+
+        This is useful in comparing the percentage of change in a time series
+        of elements.
 
         Parameters
         ----------
         periods : int, default 1
-            Periods to shift for forming percent change
+            Periods to shift for forming percent change.
         fill_method : str, default 'pad'
-            How to handle NAs before computing percent changes
+            How to handle NAs before computing percent changes.
         limit : int, default None
-            The number of consecutive NAs to fill before stopping
+            The number of consecutive NAs to fill before stopping.
         freq : DateOffset, timedelta, or offset alias string, optional
-            Increment to use from time series API (e.g. 'M' or BDay())
+            Increment to use from time series API (e.g. 'M' or BDay()).
+        **kwargs : mapping, optional
+            Additional keyword arguments are passed into
+            ``DataFrame.shift``/``Series.shift``.
 
         Returns
         -------
-        chg : %(klass)s
+        chg : Series or DataFrame, same type as the calling object
 
         Notes
         -----
-
         By default, the percentage change is calculated along the stat
         axis: 0, or ``Index``, for ``DataFrame`` and 1, or ``minor`` for
         ``Panel``. You can change this with the ``axis`` keyword argument.
+
+        Percentage change in French franc, Deutsche Mark, and Italian lira from
+        1 January 1980 to 1 March 1980.
+
+        >>> df = pd.DataFrame({
+        ...     'FR': [4.0405, 4.0963, 4.3149],
+        ...     'GR': [1.7246, 1.7482, 1.8519],
+        ...     'IT': [804.74, 810.01, 860.13]},
+        ...     index=['1980-01-01', '1980-02-01', '1980-03-01'])
+        >>> df
+                        FR      GR      IT
+        1980-01-01  4.0405  1.7246  804.74
+        1980-02-01  4.0963  1.7482  810.01
+        1980-03-01  4.3149  1.8519  860.13
+        >>> df.pct_change()
+                          FR        GR        IT
+        1980-01-01       NaN       NaN       NaN
+        1980-02-01  0.013810  0.013684  0.006549
+        1980-03-01  0.053365  0.059318  0.061876
+
+        Examples
+        --------
+        See the percentage change in a Series.
+
+        >>> s = pd.Series([90, 91, 85])
+        >>> s
+        0    90
+        1    91
+        2    85
+        dtype: int64
+        >>> s.pct_change()
+        0         NaN
+        1    0.011111
+        2   -0.065934
+        dtype: float64
+
+        See the percentage change in a Series where filling NAs with last
+        valid observation forward to next valid.
+
+        >>> s = pd.Series([90, 91, None, 85])
+        >>> s
+        0    90.0
+        1    91.0
+        2     NaN
+        3    85.0
+        dtype: float64
+        >>> s.pct_change(fill_method='ffill')
+        0         NaN
+        1    0.011111
+        2    0.000000
+        3   -0.065934
+        dtype: float64
+
+        See Also
+        --------
+        pandas.DataFrame.diff : see the difference of two columns
+        pandas.Series.diff : see the difference of two columns
         """
 
     @Appender(_shared_docs['pct_change'] % _shared_doc_kwargs)