From 6c5ec4441b2bd9aa09dd944f6af53a1a9b3bce0e Mon Sep 17 00:00:00 2001
From: Joris Van den Bossche <jorisvandenbossche@gmail.com>
Date: Wed, 16 Feb 2022 16:06:54 +0100
Subject: [PATCH] DOC: add note for ExtensionArray authors on relation between
 argmax/min and _values_for_argsort

---
 pandas/core/arrays/base.py | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/pandas/core/arrays/base.py b/pandas/core/arrays/base.py
index 834c2db9ecb21..7c0daeecafaf7 100644
--- a/pandas/core/arrays/base.py
+++ b/pandas/core/arrays/base.py
@@ -180,7 +180,7 @@ class ExtensionArray:
     * dropna
     * unique
     * factorize / _values_for_factorize
-    * argsort / _values_for_argsort
+    * argsort, argmax, argmin / _values_for_argsort
     * searchsorted
 
     The remaining methods implemented on this class should be performant,
@@ -639,7 +639,7 @@ def _values_for_argsort(self) -> np.ndarray:
         This means that the corresponding entries in the returned array don't need to
         be modified to sort correctly.
         """
-        # Note: this is used in `ExtensionArray.argsort`.
+        # Note: this is used in `ExtensionArray.argsort/argmin/argmax`.
         return np.array(self)
 
     def argsort(
@@ -676,7 +676,8 @@ def argsort(
         # Implementor note: You have two places to override the behavior of
         # argsort.
         # 1. _values_for_argsort : construct the values passed to np.argsort
-        # 2. argsort : total control over sorting.
+        # 2. argsort : total control over sorting. In case of overriding this,
+        #    it is recommended to also override argmax/argmin
         ascending = nv.validate_argsort_with_ascending(ascending, args, kwargs)
 
         values = self._values_for_argsort()
@@ -707,6 +708,10 @@ def argmin(self, skipna: bool = True) -> int:
         --------
         ExtensionArray.argmax
         """
+        # Implementor note: You have two places to override the behavior of
+        # argmin.
+        # 1. _values_for_argsort : construct the values used in nargminmax
+        # 2. argmin itself : total control over sorting.
         validate_bool_kwarg(skipna, "skipna")
         if not skipna and self._hasna:
             raise NotImplementedError
@@ -731,6 +736,10 @@ def argmax(self, skipna: bool = True) -> int:
         --------
         ExtensionArray.argmin
         """
+        # Implementor note: You have two places to override the behavior of
+        # argmax.
+        # 1. _values_for_argsort : construct the values used in nargminmax
+        # 2. argmax itself : total control over sorting.
         validate_bool_kwarg(skipna, "skipna")
         if not skipna and self._hasna:
             raise NotImplementedError