DOC: address review — move categorical map note to Examples and trim Series.map notes

Author: Talyahav17

pandas/core/arrays/categorical.py

@@ -1551,11 +1551,6 @@ 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"])
@@ -1590,6 +1585,21 @@ def map(
 
         >>> cat.map({"a": "first", "b": "second"}, na_action=None)
         Index(['first', 'second', nan], dtype='str')
+
+        The mapping function is applied to categories, not to each value. It is
+        therefore only called once per unique category, and the result reused for
+        all occurrences:
+
+        >>> cat = pd.Categorical(["a", "a", "b"])  # doctest: +SKIP
+        >>> calls = []  # doctest: +SKIP
+        >>> def f(x):  # doctest: +SKIP
+        ...     calls.append(x)
+        ...     return x.upper()
+        >>> cat.map(f)
+        ['A', 'A', 'B']
+        Categories (2, str): ['A', 'B']
+        >>> calls  # doctest: +SKIP
+        ['a', 'b']
         """
         assert callable(mapper) or is_dict_like(mapper)
 

pandas/core/series.py

@@ -4389,11 +4389,7 @@ 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
         --------