Backport PR #45237: DOC: Improve doc summaries in series.rst (#45268)

Co-authored-by: Matthew Roeschke <[email protected]>

Author: meeseeksmachine

pandas/core/arrays/categorical.py

@@ -1360,7 +1360,7 @@ def remove_unused_categories(self, inplace=no_default):
 
     def map(self, mapper):
         """
-        Map categories using input correspondence (dict, Series, or function).
+        Map categories using an input mapping or function.
 
         Maps the categories to new categories. If the mapping correspondence is
         one-to-one the result is a :class:`~pandas.Categorical` which has the

pandas/core/arrays/datetimes.py

@@ -570,7 +570,7 @@ def dtype(self) -> np.dtype | DatetimeTZDtype:  # type: ignore[override]
     @property
     def tz(self) -> tzinfo | None:
         """
-        Return timezone, if any.
+        Return the timezone.
 
         Returns
         -------
@@ -1278,7 +1278,9 @@ def day_name(self, locale=None):
     @property
     def time(self) -> npt.NDArray[np.object_]:
         """
-        Returns numpy array of datetime.time. The time part of the Timestamps.
+        Returns numpy array of :class:`datetime.time` objects.
+
+        The time part of the Timestamps.
         """
         # If the Timestamps have a timezone that is not UTC,
         # convert them into their i8 representation while
@@ -1290,16 +1292,20 @@ def time(self) -> npt.NDArray[np.object_]:
     @property
     def timetz(self) -> npt.NDArray[np.object_]:
         """
-        Returns numpy array of datetime.time also containing timezone
-        information. The time part of the Timestamps.
+        Returns numpy array of :class:`datetime.time` objects with timezone
+        information.
+
+        The time part of the Timestamps.
         """
         return ints_to_pydatetime(self.asi8, self.tz, box="time")
 
     @property
     def date(self) -> npt.NDArray[np.object_]:
         """
-        Returns numpy array of python datetime.date objects (namely, the date
-        part of Timestamps without timezone information).
+        Returns numpy array of python :class:`datetime.date` objects.
+
+        Namely, the date part of Timestamps without time and
+        timezone information.
         """
         # If the Timestamps have a timezone that is not UTC,
         # convert them into their i8 representation while

pandas/core/arrays/sparse/array.py

@@ -298,7 +298,7 @@ class SparseArray(OpsMixin, PandasObject, ExtensionArray):
             repeats of the scalar value instead.
 
     fill_value : scalar, optional
-        Elements in `data` that are `fill_value` are not stored in the
+        Elements in data that are ``fill_value`` are not stored in the
         SparseArray. For memory savings, this should be the most common value
         in `data`. By default, `fill_value` depends on the dtype of `data`:
 
@@ -1265,7 +1265,7 @@ def astype(self, dtype: AstypeArg | None = None, copy: bool = True):
 
     def map(self: SparseArrayT, mapper) -> SparseArrayT:
         """
-        Map categories using input correspondence (dict, Series, or function).
+        Map categories using an input mapping or function.
 
         Parameters
         ----------

pandas/core/groupby/groupby.py

@@ -375,8 +375,8 @@ class providing the base-class of operations.
     the results together.
 %(klass)s.groupby.aggregate : Aggregate using one or more
     operations over the specified axis.
-%(klass)s.transform : Call ``func`` on self producing a %(klass)s with
-    transformed values.
+%(klass)s.transform : Call ``func`` on self producing a %(klass)s with the
+    same axis shape as self.
 
 Notes
 -----

pandas/core/indexes/accessors.py

@@ -193,7 +193,7 @@ class DatetimeProperties(Properties):
 
     def to_pydatetime(self) -> np.ndarray:
         """
-        Return the data as an array of native Python datetime objects.
+        Return the data as an array of :class:`datetime.datetime` objects.
 
         Timezone information is retained if present.
 
@@ -333,7 +333,7 @@ class TimedeltaProperties(Properties):
 
     def to_pytimedelta(self) -> np.ndarray:
         """
-        Return an array of native `datetime.timedelta` objects.
+        Return an array of native :class:`datetime.timedelta` objects.
 
         Python's standard `datetime` library uses a different representation
         timedelta's. This method converts a Series of pandas Timedeltas

pandas/core/indexes/base.py

@@ -6029,7 +6029,7 @@ def groupby(self, values) -> PrettyDict[Hashable, np.ndarray]:
 
     def map(self, mapper, na_action=None):
         """
-        Map values using input correspondence (a dict, Series, or function).
+        Map values using an input mapping or function.
 
         Parameters
         ----------

pandas/core/indexes/category.py

@@ -506,7 +506,7 @@ def take_nd(self, *args, **kwargs):
 
     def map(self, mapper):
         """
-        Map values using input correspondence (a dict, Series, or function).
+        Map values using input an input mapping or function.
 
         Maps the values (their categories, not the codes) of the index to new
         categories. If the mapping correspondence is one-to-one the result is a

pandas/core/series.py

@@ -4145,7 +4145,7 @@ def unstack(self, level=-1, fill_value=None) -> DataFrame:
 
     def map(self, arg, na_action=None) -> Series:
         """
-        Map values of Series according to input correspondence.
+        Map values of Series according to an input mapping or function.
 
         Used for substituting each value in a Series with another value,
         that may be derived from a function, a ``dict`` or

pandas/core/shared_docs.py

@@ -96,7 +96,7 @@
     will be used to determine the groups (the Series' values are first
     aligned; see ``.align()`` method). If a list or ndarray of length
     equal to the selected axis is passed (see the `groupby user guide
-    <https://pandas.pydata.org/pandas-docs/stable/user_guide/groupby.html#splitting-an-object-into-groups>`),
+    <https://pandas.pydata.org/pandas-docs/stable/user_guide/groupby.html#splitting-an-object-into-groups>`_),
     the values are used as-is to determine the groups. A label or list
     of labels may be passed to group by the columns in ``self``.
     Notice that a tuple is interpreted as a (single) key.
@@ -267,9 +267,7 @@
 _shared_docs[
     "transform"
 ] = """
-Call ``func`` on self producing a {klass} with transformed values.
-
-Produced {klass} will have same axis length as self.
+Call ``func`` on self producing a {klass} with the same axis shape as self.
 
 Parameters
 ----------