From ed57b848d6093b33abd3f5a6da10a4efa0a404aa Mon Sep 17 00:00:00 2001
From: William Joshua King <wgk4@duke.edu>
Date: Tue, 20 Feb 2024 16:36:13 -0500
Subject: [PATCH] ES01 Extended Summaries for Categorical

---
 ci/code_checks.sh                 |  6 ------
 pandas/core/arrays/categorical.py | 30 ++++++++++++++++++++++++++++++
 2 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/ci/code_checks.sh b/ci/code_checks.sh
index 231d40e17c0c0..459a9458ca174 100755
--- a/ci/code_checks.sh
+++ b/ci/code_checks.sh
@@ -416,13 +416,7 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
 
     MSG='Partially validate docstrings (ES01)' ;  echo $MSG
     $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=ES01 --ignore_functions \
-        pandas.Categorical.__array__\
-        pandas.Categorical.as_ordered\
-        pandas.Categorical.as_unordered\
         pandas.Categorical.dtype\
-        pandas.Categorical.ordered\
-        pandas.Categorical.remove_unused_categories\
-        pandas.Categorical.rename_categories\
         pandas.CategoricalDtype\
         pandas.CategoricalDtype.categories\
         pandas.CategoricalDtype.ordered\
diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py
index d1dba024e85c5..b04826b227ac6 100644
--- a/pandas/core/arrays/categorical.py
+++ b/pandas/core/arrays/categorical.py
@@ -837,6 +837,11 @@ def ordered(self) -> Ordered:
         """
         Whether the categories have an ordered relationship.
 
+        Returns whether the categories can be ordered.
+        Ordered categories can be sorted, and operations such
+        as .min() and .max() make sense and do not raise a
+        TypeError.
+
         Examples
         --------
         For :class:`pandas.Series`:
@@ -981,6 +986,11 @@ def as_ordered(self) -> Self:
         """
         Set the Categorical to be ordered.
 
+        Creates a new object that contains the same categories
+        as the input, but is ordered. This means that the
+        categories can be sorted, and .min() and .max() operations
+        do not raise a TypeError.
+
         Returns
         -------
         Categorical
@@ -1012,6 +1022,11 @@ def as_unordered(self) -> Self:
         """
         Set the Categorical to be unordered.
 
+        Creates a new object that contains the same categories
+        as the input, but is not ordered. This means that the
+        categories cannot be sorted, and .min() and .max()
+        operations raise a TypeError.
+
         Returns
         -------
         Categorical
@@ -1154,6 +1169,9 @@ def rename_categories(self, new_categories) -> Self:
         """
         Rename categories.
 
+        Renames the categories using an array, a map, or
+        a lambda function.
+
         Parameters
         ----------
         new_categories : list-like, dict-like or callable
@@ -1430,6 +1448,11 @@ def remove_unused_categories(self) -> Self:
         """
         Remove categories which are not used.
 
+        Categorical arrays are mutable, and as such
+        it is possible that some of the initial categories
+        are no longer used down the line. This removes
+        original categories that are no longer in use.
+
         Returns
         -------
         Categorical
@@ -1657,6 +1680,13 @@ def __array__(self, dtype: NpDtype | None = None) -> np.ndarray:
         """
         The numpy array interface.
 
+        This defines the __array__ method within a Pandas Categorical
+        class, making it compatible with numpy arrays.
+
+        The method returns a numpy array representation of the categorical
+        data. It accepts an optional dtype parameter, allowing the user
+        to specify the data type of the resulting numpy array.
+
         Returns
         -------
         numpy.array