DOC: modify examples and return in docs

Author: Axeldnahcram

pandas/core/groupby/generic.py

@@ -1321,8 +1321,8 @@ def idxmin(self, skipna: bool = True) -> Series:
 
         Returns
         -------
-        Index
-            Label of the minimum value.
+        Series
+            Indexes of minima in each group.
 
         Raises
         ------
@@ -1374,8 +1374,8 @@ def idxmax(self, skipna: bool = True) -> Series:
 
         Returns
         -------
-        Index
-            Label of the maximum value.
+        Series
+            Indexes of maxima in each group.
 
         Raises
         ------
@@ -2508,8 +2508,8 @@ def idxmax(
 
         Returns
         -------
-        Series
-            Indexes of maxima in each group.
+        DataFrame
+            Indexes of maxima in each column according to the group.
 
         Raises
         ------
@@ -2519,6 +2519,7 @@ def idxmax(
         See Also
         --------
         Series.idxmax : Return index of the maximum element.
+        DataFrame.idxmax : Indexes of maxima along the specified axis.
 
         Notes
         -----
@@ -2532,6 +2533,7 @@ def idxmax(
         ...     {
         ...         "consumption": [10.51, 103.11, 55.48],
         ...         "co2_emissions": [37.2, 19.66, 1712],
+        ...         "food_type": ["meat", "plant", "meat"]
         ...     },
         ...     index=["Pork", "Wheat Products", "Beef"],
         ... )
@@ -2542,12 +2544,14 @@ def idxmax(
         Wheat Products       103.11         19.66
         Beef                  55.48       1712.00
 
-        By default, it returns the index for the maximum value in each column.
+        By default, it returns the index for the maximum value in each column according to the group.
+
+        >>> df.groupby("food_type").idxmax()
+                        consumption   co2_emissions
+        animal_type                                
+        animal                 Beef            Beef
+        plant        Wheat Products  Wheat Products
 
-        >>> df.idxmax()
-        consumption     Wheat Products
-        co2_emissions             Beef
-        dtype: object
         """
         return self._idxmax_idxmin("idxmax", numeric_only=numeric_only, skipna=skipna)
 
@@ -2570,8 +2574,8 @@ def idxmin(
 
         Returns
         -------
-        Series
-            Indexes of minima in each group.
+        DataFrame
+            Indexes of minima in each column according to the group.
 
         Raises
         ------
@@ -2581,6 +2585,7 @@ def idxmin(
         See Also
         --------
         Series.idxmin : Return index of the minimum element.
+        DataFrame.idxmin : Indexes of minima along the specified axis.
 
         Notes
         -----
@@ -2594,6 +2599,7 @@ def idxmin(
         ...     {
         ...         "consumption": [10.51, 103.11, 55.48],
         ...         "co2_emissions": [37.2, 19.66, 1712],
+        ...         "food_type": ["meat", "plant", "meat"]
         ...     },
         ...     index=["Pork", "Wheat Products", "Beef"],
         ... )
@@ -2607,9 +2613,10 @@ def idxmin(
         By default, it returns the index for the minimum value in each column.
 
         >>> df.idxmin()
-        consumption                Pork
-        co2_emissions    Wheat Products
-        dtype: object
+                        consumption   co2_emissions
+        animal_type                                
+        animal                 Pork            Pork
+        plant        Wheat Products  Wheat Products
         """
         return self._idxmax_idxmin("idxmin", numeric_only=numeric_only, skipna=skipna)