DOC: update the pandas.DataFrame.diff docstring

Author: adatasetaday

pandas/core/generic.py

@@ -3605,7 +3605,11 @@ def f(x):
 
     def head(self, n=5):
         """
-        Return the first n rows.
+        Return the first `n` rows.
+
+        This function returns the first `n` rows for the object based on the
+        underlying index. It is useful for quickly testing if your object
+        has the right type of data in it.
 
         Parameters
         ----------
@@ -3619,7 +3623,7 @@ def head(self, n=5):
 
         See Also
         --------
-        pandas.DataFrame.tail
+        pandas.DataFrame.tail: Returns the last `n` rows.
 
         Examples
         --------

pandas/core/indexes/base.py

@@ -2256,18 +2256,19 @@ def sortlevel(self, level=None, ascending=True, sort_remaining=None):
         return self.sort_values(return_indexer=True, ascending=ascending)
 
     def shift(self, periods=1, freq=None):
-        """Shift index by desired number of time frequency increments.
+        """
+        Shift index by desired number of time frequency increments.
 
         This method is for shifting the values of datetime-like indexes
         by a specified time increment a given number of times.
 
         Parameters
         ----------
-        periods : int
+        periods : int, default 1
             Number of periods (or increments) to shift by,
-            can be positive or negative (default is 1).
-        freq : pandas.DateOffset, pandas.Timedelta or string
-            Frequency increment to shift by (default is None).
+            can be positive or negative.
+        freq : pandas.DateOffset, pandas.Timedelta or string, optional
+            Frequency increment to shift by.
             If None, the index is shifted by its own `freq` attribute.
             Offset aliases are valid strings, e.g., 'D', 'W', 'M' etc.
 
@@ -2276,6 +2277,10 @@ def shift(self, periods=1, freq=None):
         pandas.Index
             shifted index
 
+        See Also
+        --------
+        Series.shift : Shift values of Series.
+
         Examples
         --------
         Put the first 5 month starts of 2011 into an index.