DOC: clarify Series.map behavior for categorical dtype

Author: Talyahav17

pandas/core/arrays/categorical.py

@@ -1551,6 +1551,11 @@ def map(
         Series.apply : Apply more complex functions on a
             :class:`~pandas.Series`.
 
+        Notes
+        -----
+        The mapping function is applied to the categories, not to
+        each element of the array.
+
         Examples
         --------
         >>> cat = pd.Categorical(["a", "b", "c"])

pandas/core/series.py

@@ -4389,6 +4389,12 @@ def map(
         provides a method for default values), then this default is used
         rather than ``NaN``.
 
+        When the Series has ``⁠dtype="category"⁠``, the function is applied
+        to the categories and not to each individual value. This means
+        that if the same category appears multiple times, the function is
+        only called once for that category, and the result is reused for
+        all occurrences. Missing values (NaN) are not passed to the function.
+
         Examples
         --------
         >>> s = pd.Series(["cat", "dog", np.nan, "rabbit"])
@@ -4428,6 +4434,34 @@ def map(
         2            NaN
         3  I am a rabbit
         dtype: object
+
+        For categorical data, the function is only applied to the categories:
+
+        >>> s = pd.Series(list("cabaa"))
+        >>> s.map(print)
+        c
+        a
+        b
+        a
+        a
+        0    None
+        1    None
+        2    None
+        3    None
+        4    None
+        dtype: object
+
+        >>> s_cat = s.astype("category")
+        >>> s_cat.map(print)  # function called once per unique category
+        a
+        b
+        c
+        0    None
+        1    None
+        2    None
+        3    None
+        4    None
+        dtype: object
         """
         if func is None:
             if "arg" in kwargs: