DOC: Partial fix SA04 errors in docstrings #28792

Author: drollolo

pandas/core/accessor.py

@@ -282,7 +282,8 @@ def decorator(accessor):
 @doc(
     _register_accessor,
     klass="DataFrame",
-    others="register_series_accessor, register_index_accessor",
+    others=("register_series_accessor : Register a custom accessor on Series objects.\n"
+            "register_index_accessor : Register a custom accessor on Index objects."),
 )
 def register_dataframe_accessor(name):
     from pandas import DataFrame
@@ -293,7 +294,12 @@ def register_dataframe_accessor(name):
 @doc(
     _register_accessor,
     klass="Series",
-    others="register_dataframe_accessor, register_index_accessor",
+    others="""
+           register_dataframe_accessor : Register a custom accessor on
+                  DataFrame objects.
+           register_index_accessor : Register a custom accessor on
+                  Index objects.
+           """,
 )
 def register_series_accessor(name):
     from pandas import Series
@@ -304,7 +310,8 @@ def register_series_accessor(name):
 @doc(
     _register_accessor,
     klass="Index",
-    others="register_dataframe_accessor, register_series_accessor",
+    others="""register_dataframe_accessor : Register a custom accessor on DataFrame objects.
+           register_series_accessor : Register a custom accessor on Series objects.""",
 )
 def register_index_accessor(name):
     from pandas import Index

pandas/core/arrays/categorical.py

@@ -416,12 +416,12 @@ def categories(self):
 
         See Also
         --------
-        rename_categories
-        reorder_categories
-        add_categories
-        remove_categories
-        remove_unused_categories
-        set_categories
+        rename_categories : Rename categories.
+        reorder_categories : Reorder categories.
+        add_categories : Add new categories.
+        remove_categories : Remove the specified categories.
+        remove_unused_categories : Remove categories which are not used.
+        set_categories : Set the categories to the specified categories.
         """
         return self.dtype.categories
 
@@ -834,11 +834,11 @@ def set_categories(self, new_categories, ordered=None, rename=False, inplace=Fal
 
         See Also
         --------
-        rename_categories
-        reorder_categories
-        add_categories
-        remove_categories
-        remove_unused_categories
+        rename_categories : Rename categories.
+        reorder_categories : Reorder categories.
+        add_categories : Add new categories.
+        remove_categories : Remove the specified categories.
+        remove_unused_categories : Remove categories which are not used.
         """
         inplace = validate_bool_kwarg(inplace, "inplace")
         if ordered is None:
@@ -905,11 +905,11 @@ def rename_categories(self, new_categories, inplace=False):
 
         See Also
         --------
-        reorder_categories
-        add_categories
-        remove_categories
-        remove_unused_categories
-        set_categories
+        reorder_categories : Reorder categories.
+        add_categories : Add new categories.
+        remove_categories : Remove the specified categories.
+        remove_unused_categories : Remove categories which are not used.
+        set_categories : Set the categories to the specified categories.
 
         Examples
         --------
@@ -973,11 +973,11 @@ def reorder_categories(self, new_categories, ordered=None, inplace=False):
 
         See Also
         --------
-        rename_categories
-        add_categories
-        remove_categories
-        remove_unused_categories
-        set_categories
+        rename_categories : Rename categories.
+        add_categories : Add new categories.
+        remove_categories : Remove the specified categories.
+        remove_unused_categories : Remove categories which are not used.
+        set_categories : Set the categories to the specified categories.
         """
         inplace = validate_bool_kwarg(inplace, "inplace")
         if set(self.dtype.categories) != set(new_categories):
@@ -1013,11 +1013,11 @@ def add_categories(self, new_categories, inplace=False):
 
         See Also
         --------
-        rename_categories
-        reorder_categories
-        remove_categories
-        remove_unused_categories
-        set_categories
+        rename_categories : Rename categories.
+        reorder_categories : Reorder categories.
+        remove_categories : Remove the specified categories.
+        remove_unused_categories : Remove categories which are not used.
+        set_categories : Set the categories to the specified categories.
         """
         inplace = validate_bool_kwarg(inplace, "inplace")
         if not is_list_like(new_categories):
@@ -1062,11 +1062,11 @@ def remove_categories(self, removals, inplace=False):
 
         See Also
         --------
-        rename_categories
-        reorder_categories
-        add_categories
-        remove_unused_categories
-        set_categories
+        rename_categories : Rename categories.
+        reorder_categories : Reorder categories.
+        add_categories : Add new categories.
+        remove_unused_categories : Remove categories which are not used.
+        set_categories : Set the categories to the specified categories.
         """
         inplace = validate_bool_kwarg(inplace, "inplace")
         if not is_list_like(removals):
@@ -1104,11 +1104,11 @@ def remove_unused_categories(self, inplace=False):
 
         See Also
         --------
-        rename_categories
-        reorder_categories
-        add_categories
-        remove_categories
-        set_categories
+        rename_categories : Rename categories.
+        reorder_categories : Reorder categories.
+        add_categories : Add new categories.
+        remove_categories : Remove the specified categories.
+        set_categories : Set the categories to the specified categories.
         """
         inplace = validate_bool_kwarg(inplace, "inplace")
         cat = self if inplace else self.copy()

pandas/core/dtypes/dtypes.py

@@ -194,7 +194,7 @@ class CategoricalDtype(PandasExtensionDtype, ExtensionDtype):
 
     See Also
     --------
-    Categorical
+    Categorical : Represent a categorical variable in classic R / S-plus fashion.
 
     Notes
     -----

pandas/core/indexes/multi.py

@@ -1566,7 +1566,8 @@ def to_frame(self, index=True, name=None):
 
         See Also
         --------
-        DataFrame
+        DataFrame : Two-dimensional, size-mutable, potentially heterogeneous
+            tabular data.
         """
         from pandas import DataFrame
 

pandas/core/ops/docstrings.py

@@ -33,9 +33,14 @@ def _make_flex_doc(op_name, typ):
             desc=op_desc["desc"],
             op_name=op_name,
             equiv=equiv,
-            reverse=op_desc["reverse"],
             series_returns=op_desc["series_returns"],
         )
+        if op_desc["reverse"]:
+            doc_see_also = _see_also_reverse_SERIES.format(
+                reverse=op_desc["reverse"],
+                see_also_desc=op_desc["see_also_desc"],
+            )
+            doc_no_examples = doc_no_examples + doc_see_also
         if op_desc["series_examples"]:
             doc = doc_no_examples + op_desc["series_examples"]
         else:
@@ -352,6 +357,8 @@ def _make_flex_doc(op_name, typ):
     if reverse_op is not None:
         _op_descriptions[reverse_op] = _op_descriptions[key].copy()
         _op_descriptions[reverse_op]["reverse"] = key
+        _op_descriptions[key]["see_also_desc"] = f"Reversed {_op_descriptions[key]['desc']}"
+        _op_descriptions[reverse_op]["see_also_desc"] = f"Usual {_op_descriptions[key]['desc']}"
 
 _flex_doc_SERIES = """
 Return {desc} of series and other, element-wise (binary operator `{op_name}`).
@@ -374,10 +381,12 @@ def _make_flex_doc(op_name, typ):
 Returns
 -------
 {series_returns}
+"""
 
+_see_also_reverse_SERIES = """
 See Also
 --------
-Series.{reverse}
+Series.{reverse} : {see_also_desc}.
 """
 
 _arith_doc_FRAME = """

pandas/core/window/rolling.py

@@ -1885,8 +1885,8 @@ def _validate_freq(self):
         """
     See Also
     --------
-    Series.rolling
-    DataFrame.rolling
+    pandas.Series.rolling : Series rolling.
+    pandas.DataFrame.rolling : DataFrame rolling.
     """
     )
 

pandas/io/html.py

@@ -1036,7 +1036,7 @@ def read_html(
 
     See Also
     --------
-    read_csv
+    read_csv : Read a comma-separated values (csv) file into DataFrame.
 
     Notes
     -----

pandas/io/sql.py

@@ -313,7 +313,7 @@ def read_sql_query(
     See Also
     --------
     read_sql_table : Read SQL database table into a DataFrame.
-    read_sql
+    read_sql : Read SQL query or database table into a DataFrame.
 
     Notes
     -----

pandas/plotting/_misc.py

@@ -29,7 +29,7 @@ def table(ax, data, rowLabels=None, colLabels=None, **kwargs):
 
 def register():
     """
-    Register Pandas Formatters and Converters with matplotlib.
+    Register pandas Formatters and Converters with matplotlib.
 
     This function modifies the global ``matplotlib.units.registry``
     dictionary. Pandas adds custom converters for
@@ -43,7 +43,7 @@ def register():
 
     See Also
     --------
-    deregister_matplotlib_converters
+    deregister_matplotlib_converters : Remove pandas’ formatters and converters.
     """
     plot_backend = _get_plot_backend("matplotlib")
     plot_backend.register()
@@ -62,7 +62,8 @@ def deregister():
 
     See Also
     --------
-    register_matplotlib_converters
+    register_matplotlib_converters : Register pandas Formatters and Converters
+        with matplotlib.
     """
     plot_backend = _get_plot_backend("matplotlib")
     plot_backend.deregister()

pandas/tseries/frequencies.py

@@ -91,7 +91,7 @@ def to_offset(freq) -> Optional[DateOffset]:
 
     See Also
     --------
-    DateOffset
+    DateOffset : Standard kind of date increment used for a date range.
 
     Examples
     --------