DOC: Document behaviour of head(n), tail(n) for negative values of n except on GroupBy (#30556)

* DOC: Document negative values on head(n), tail(n) except for GroupBy

Author: bharatr21

pandas/core/generic.py

@@ -4652,14 +4652,17 @@ def head(self: FrameOrSeries, n: int = 5) -> FrameOrSeries:
         on position. It is useful for quickly testing if your object
         has the right type of data in it.
 
+        For negative values of `n`, this function returns all rows except
+        the last `n` rows, equivalent to ``df[:-n]``.
+
         Parameters
         ----------
         n : int, default 5
             Number of rows to select.
 
         Returns
         -------
-        obj_head : same type as caller
+        same type as caller
             The first `n` rows of the caller object.
 
         See Also
@@ -4699,6 +4702,17 @@ def head(self: FrameOrSeries, n: int = 5) -> FrameOrSeries:
         0  alligator
         1        bee
         2     falcon
+
+        For negative values of `n`
+
+        >>> df.head(-3)
+              animal
+        0  alligator
+        1        bee
+        2     falcon
+        3       lion
+        4     monkey
+        5     parrot
         """
 
         return self.iloc[:n]
@@ -4711,6 +4725,9 @@ def tail(self: FrameOrSeries, n: int = 5) -> FrameOrSeries:
         position. It is useful for quickly verifying data, for example,
         after sorting or appending rows.
 
+        For negative values of `n`, this function returns all rows except
+        the first `n` rows, equivalent to ``df[n:]``.
+
         Parameters
         ----------
         n : int, default 5
@@ -4758,6 +4775,17 @@ def tail(self: FrameOrSeries, n: int = 5) -> FrameOrSeries:
         6  shark
         7  whale
         8  zebra
+
+        For negative values of `n`
+
+        >>> df.tail(-3)
+           animal
+        3    lion
+        4  monkey
+        5  parrot
+        6   shark
+        7   whale
+        8   zebra
         """
 
         if n == 0:

pandas/core/groupby/groupby.py

@@ -2377,6 +2377,8 @@ def head(self, n=5):
         from the original DataFrame with original index and order preserved
         (``as_index`` flag is ignored).
 
+        Does not work for negative values of `n`.
+
         Returns
         -------
         Series or DataFrame
@@ -2390,6 +2392,10 @@ def head(self, n=5):
            A  B
         0  1  2
         2  5  6
+        >>> df.groupby('A').head(-1)
+        Empty DataFrame
+        Columns: [A, B]
+        Index: []
         """
         self._reset_group_selection()
         mask = self._cumcount_array() < n
@@ -2405,6 +2411,8 @@ def tail(self, n=5):
         from the original DataFrame with original index and order preserved
         (``as_index`` flag is ignored).
 
+        Does not work for negative values of `n`.
+
         Returns
         -------
         Series or DataFrame
@@ -2418,6 +2426,10 @@ def tail(self, n=5):
            A  B
         1  a  2
         3  b  2
+        >>> df.groupby('A').tail(-1)
+        Empty DataFrame
+        Columns: [A, B]
+        Index: []
         """
         self._reset_group_selection()
         mask = self._cumcount_array(ascending=False) < n