DOC: Fixing SA04 errors as per #25337

ci/code_checks.sh

@@ -241,8 +241,10 @@ fi
 ### DOCSTRINGS ###
 if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
 
-    MSG='Validate docstrings (GL06, GL07, GL09, SS04, SS05, PR03, PR04, PR05, PR10, EX04, RT04, RT05, SA05)' ; echo $MSG
-    $BASE_DIR/scripts/validate_docstrings.py --format=azure --errors=GL06,GL07,GL09,SS04,SS05,PR03,PR04,PR05,PR10,EX04,RT04,RT05,SA05
+
+    MSG='Validate docstrings (GL06, GL07, GL09, SS04, SS05, PR03, PR04, PR05, PR10, EX04, RT04, RT05, SA04 SA05)' ; echo $MSG
+    $BASE_DIR/scripts/validate_docstrings.py --format=azure --errors=GL06,GL07,GL09,SS04,SS05,PR03,PR04,PR05,PR10,EX04,RT04,RT05,SA04,SA05
+
     RET=$(($RET + $?)) ; echo $MSG "DONE"
 
 fi

pandas/_libs/tslibs/timedeltas.pyx

@@ -1089,7 +1089,7 @@ cdef class _Timedelta(timedelta):
 
         See Also
         --------
-        Timestamp.isoformat
+        Timestamp.isoformat: Format Timestamp as ISO 8601
 
         Notes
         -----

pandas/core/accessor.py

@@ -262,24 +262,30 @@ def plot(self):
 
 
 @Appender(_doc % dict(klass="DataFrame",
-                      others=("register_series_accessor, "
-                              "register_index_accessor")))
+                      others=("register_series_accessor: Register a custom"
+                              "accessor on DataFrame objects."
+                              "register_index_accessor: Register a custom"
+                              "accessor on Index objects.")))
 def register_dataframe_accessor(name):
     from pandas import DataFrame
     return _register_accessor(name, DataFrame)
 
 
 @Appender(_doc % dict(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
     return _register_accessor(name, Series)
 
 
 @Appender(_doc % dict(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
     return _register_accessor(name, Index)

pandas/core/algorithms.py

@@ -300,8 +300,8 @@ def unique(values):
 
     See Also
     --------
-    Index.unique
-    Series.unique
+    Index.unique: Return unique values in the index.
+    Series.unique: Return unique values of Series object.
 
     Examples
     --------

pandas/core/arrays/base.py

@@ -171,8 +171,10 @@ def _from_factorized(cls, values, original):
 
         See Also
         --------
-        pandas.factorize
-        ExtensionArray.factorize
+        pandas.factorize: Encode the object as an enumerated type or
+            categorical variable.
+        ExtensionArray.factorize: Encode the extension array as
+            an enumerated type.
         """
         raise AbstractMethodError(cls)
 
@@ -377,7 +379,7 @@ def _values_for_argsort(self):
 
         See Also
         --------
-        ExtensionArray.argsort
+        ExtensionArray.argsort: Return the indices that would sort this array.
         """
         # Note: this is used in `ExtensionArray.argsort`.
         return np.array(self)
@@ -403,7 +405,7 @@ def argsort(self, ascending=True, kind='quicksort', *args, **kwargs):
 
         See Also
         --------
-        numpy.argsort : Sorting implementation used internally.
+        numpy.argsort : Sort implementation used internally.
         """
         # Implementor note: You have two places to override the behavior of
         # argsort.
@@ -647,7 +649,7 @@ def factorize(self, na_sentinel=-1):
 
         See Also
         --------
-        pandas.factorize : Top-level factorize method that dispatches here.
+        pandas.factorize: Top-level factorize method that dispatches here.
 
         Notes
         -----
@@ -776,8 +778,8 @@ def take(self, indices, allow_fill=False, fill_value=None):
 
         See Also
         --------
-        numpy.take
-        pandas.api.extensions.take
+        numpy.take: Take elements from an array along an axis.
+        pandas.api.extensions.take: Take elements from an array.
 
         Examples
         --------

pandas/core/arrays/categorical.py

@@ -276,8 +276,8 @@ class Categorical(ExtensionArray, PandasObject):
 
     See Also
     --------
-    api.types.CategoricalDtype : Type for categorical data.
-    CategoricalIndex : An Index with an underlying ``Categorical``.
+    api.types.CategoricalDtype: Type for categorical data.
+    CategoricalIndex: An Index with an underlying ``Categorical``.
 
     Notes
     -----
@@ -421,12 +421,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 into specified new categories.
+        add_categories: Add new categories.
+        remove_categories: Remove specified categories.
+        remove_unused_categories: Remove unused categories.
+        set_categories: Set new categories inplace.
         """
         return self.dtype.categories
 
@@ -836,11 +836,11 @@ def set_categories(self, new_categories, ordered=None, rename=False,
 
         See Also
         --------
-        rename_categories
-        reorder_categories
-        add_categories
-        remove_categories
-        remove_unused_categories
+        rename_categories: Rename categories.
+        reorder_categories: Reorder categories into specified new categories.
+        add_categories: Add new categories.
+        remove_categories: Remove specified categories.
+        remove_unused_categorie: Remove unused categories.
         """
         inplace = validate_bool_kwarg(inplace, 'inplace')
         if ordered is None:
@@ -908,11 +908,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 into specified new categories.
+        add_categories: Add new categories.
+        remove_categories: Remove specified categories.
+        remove_unused_categories: Remove unused categories.
+        set_categories: Set new categories inplace.
 
         Examples
         --------
@@ -986,11 +986,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 specified categories.
+        remove_unused_categories: Remove unused categories.
+        set_categories: Set new categories inplace.
         """
         inplace = validate_bool_kwarg(inplace, 'inplace')
         if set(self.dtype.categories) != set(new_categories):
@@ -1026,11 +1026,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 into specified new categories.
+        remove_categories: Remove specified categories.
+        remove_unused_categories: Remove unused categories.
+        set_categories: Set new categories inplace.
         """
         inplace = validate_bool_kwarg(inplace, 'inplace')
         if not is_list_like(new_categories):
@@ -1075,11 +1075,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 into specified new categories.
+        add_categories: Add new categories.
+        remove_unused_categories: Remove unused categories.
+        set_categories: Set new categories inplace.
         """
         inplace = validate_bool_kwarg(inplace, 'inplace')
         if not is_list_like(removals):
@@ -1118,11 +1118,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: Reorders categories into specified new categories.
+        add_categories: Add new categories.
+        remove_categories: Remove specified categories.
+        set_categories: Set new categories inplace.
         """
         inplace = validate_bool_kwarg(inplace, 'inplace')
         cat = self if inplace else self.copy()
@@ -1366,7 +1366,8 @@ def memory_usage(self, deep=False):
 
         See Also
         --------
-        numpy.ndarray.nbytes
+        numpy.ndarray.nbytes: Total bytes consumed by the elements of the
+            array.
         """
         return self._codes.nbytes + self.dtype.categories.memory_usage(
             deep=deep)
@@ -1403,7 +1404,6 @@ def isna(self):
         isna : Top-level isna.
         isnull : Alias of isna.
         Categorical.notna : Boolean inverse of Categorical.isna.
-
         """
 
         ret = self._codes == -1
@@ -1423,10 +1423,9 @@ def notna(self):
 
         See Also
         --------
-        notna : Top-level notna.
-        notnull : Alias of notna.
-        Categorical.isna : Boolean inverse of Categorical.notna.
-
+        notna: Top-level notna.
+        notnull: Alias of notna.
+        Categorical.isna: Boolean inverse of Categorical.notna.
         """
         return ~self.isna()
     notnull = notna
@@ -1469,8 +1468,8 @@ def value_counts(self, dropna=True):
 
         See Also
         --------
-        Series.value_counts
-
+        Series.value_counts: Return a Series containing counts of unique
+            values.
         """
         from numpy import bincount
         from pandas import Series, CategoricalIndex
@@ -1544,7 +1543,7 @@ def argsort(self, *args, **kwargs):
 
         See Also
         --------
-        numpy.ndarray.argsort
+        numpy.ndarray.argsort: Return the indices that would sort this array.
 
         Notes
         -----
@@ -1597,8 +1596,9 @@ def sort_values(self, inplace=False, ascending=True, na_position='last'):
 
         See Also
         --------
-        Categorical.sort
-        Series.sort_values
+        Categorical.sort: Sort the Category inplace by category value.
+        Series.sort_values: Sort a Series in ascending or descending
+            order by some criterion.
 
         Examples
         --------
@@ -1845,8 +1845,8 @@ def take_nd(self, indexer, allow_fill=None, fill_value=None):
 
         See Also
         --------
-        Series.take : Similar method for Series.
-        numpy.ndarray.take : Similar method for NumPy arrays.
+        Series.take: Similar method for Series.
+        numpy.ndarray.take: Similar method for NumPy arrays.
 
         Examples
         --------
@@ -2294,9 +2294,12 @@ def unique(self):
 
         See Also
         --------
-        unique
-        CategoricalIndex.unique
-        Series.unique
+        unique: Hash table-based unique. Uniques are returned in order of
+            appearance. This does NOT sort.
+        CategoricalIndex.unique: Return Index of unique values in the object.
+            Includes NA values. The order of the original is preserved.
+        Series.unique: Return Index of unique values in the object. Includes
+            NA values. The order of the original is preserved.
 
         """
 
@@ -2427,7 +2430,7 @@ def isin(self, values):
 
         See Also
         --------
-        pandas.Series.isin : Equivalent method on Series.
+        pandas.Series.isin: Equivalent method on Series.
 
         Examples
         --------