fixes #6721 GroupBy.head()/tail() documentation

Author: mtrbean

pandas/core/groupby/groupby.py

@@ -2326,8 +2326,9 @@ def head(self, n=5):
         """
         Return first n rows of each group.
 
-        Essentially equivalent to ``.apply(lambda x: x.head(n))``,
-        except ignores as_index flag.
+        Similar to ``.apply(lambda x: x.head(n))``, but it returns a subset of rows
+        from the original DataFrame with original index preserved (``as_index`` flag
+        is ignored).
 
         Returns
         -------
@@ -2338,11 +2339,11 @@ def head(self, n=5):
 
         >>> df = pd.DataFrame([[1, 2], [1, 4], [5, 6]],
         ...                   columns=['A', 'B'])
-        >>> df.groupby('A', as_index=False).head(1)
+        >>> df.groupby('A', as_index=True).head(1)
            A  B
         0  1  2
         2  5  6
-        >>> df.groupby('A').head(1)
+        >>> df.groupby('A', as_index=False).head(1)
            A  B
         0  1  2
         2  5  6
@@ -2357,8 +2358,9 @@ def tail(self, n=5):
         """
         Return last n rows of each group.
 
-        Essentially equivalent to ``.apply(lambda x: x.tail(n))``,
-        except ignores as_index flag.
+        Similar to ``.apply(lambda x: x.tail(n))``, but it returns a subset of rows
+        from the original DataFrame with original index preserved (``as_index`` flag
+        is ignored).
 
         Returns
         -------