DOC: Fix validation error type RT01 and check in CI (#25356)

ci/code_checks.sh

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

pandas/core/accessor.py

@@ -206,6 +206,11 @@ def decorator(accessor):
     Name under which the accessor should be registered. A warning is issued
     if this name conflicts with a preexisting attribute.
 
+Returns
+-------
+callable
+    A class decorator.
+
 See Also
 --------
 %(others)s

pandas/core/arrays/categorical.py

@@ -619,6 +619,10 @@ def from_codes(cls, codes, categories=None, ordered=None, dtype=None):
                When `dtype` is provided, neither `categories` nor `ordered`
                should be provided.
 
+        Returns
+        -------
+        Categorical
+
         Examples
         --------
         >>> dtype = pd.CategoricalDtype(['a', 'b'], ordered=True)
@@ -756,6 +760,11 @@ def as_ordered(self, inplace=False):
         inplace : bool, default False
            Whether or not to set the ordered attribute in-place or return
            a copy of this categorical with ordered set to True.
+
+        Returns
+        -------
+        Categorical
+            Ordered Categorical.
         """
         inplace = validate_bool_kwarg(inplace, 'inplace')
         return self.set_ordered(True, inplace=inplace)
@@ -769,6 +778,11 @@ def as_unordered(self, inplace=False):
         inplace : bool, default False
            Whether or not to set the ordered attribute in-place or return
            a copy of this categorical with ordered set to False.
+
+        Returns
+        -------
+        Categorical
+            Unordered Categorical.
         """
         inplace = validate_bool_kwarg(inplace, 'inplace')
         return self.set_ordered(False, inplace=inplace)

pandas/core/arrays/interval.py

@@ -239,6 +239,10 @@ def _from_factorized(cls, values, original):
 
         .. versionadded:: 0.23.0
 
+    Returns
+    -------
+    %(klass)s
+
     See Also
     --------
     interval_range : Function to create a fixed frequency IntervalIndex.
@@ -383,6 +387,10 @@ def from_arrays(cls, left, right, closed='right', copy=False, dtype=None):
 
         ..versionadded:: 0.23.0
 
+    Returns
+    -------
+    %(klass)s
+
     See Also
     --------
     interval_range : Function to create a fixed frequency IntervalIndex.

pandas/core/base.py

@@ -656,6 +656,10 @@ class IndexOpsMixin:
     def transpose(self, *args, **kwargs):
         """
         Return the transpose, which is by definition self.
+
+        Returns
+        -------
+        %(klass)s
         """
         nv.validate_transpose(args, kwargs)
         return self
@@ -696,6 +700,11 @@ def ndim(self):
     def item(self):
         """
         Return the first element of the underlying data as a python scalar.
+
+        Returns
+        -------
+        scalar
+            The first element of %(klass)s.
         """
         return self.values.item()
 
@@ -1016,6 +1025,11 @@ def argmax(self, axis=None, skipna=True):
             Dummy argument for consistency with Series
         skipna : bool, default True
 
+        Returns
+        -------
+        numpy.ndarray
+            Indices of the maximum values.
+
         See Also
         --------
         numpy.ndarray.argmax
@@ -1116,6 +1130,10 @@ def __iter__(self):
         These are each a scalar type, which is a Python scalar
         (for str, int, float) or a pandas scalar
         (for Timestamp/Timedelta/Interval/Period)
+
+        Returns
+        -------
+        iterator
         """
         # We are explicity making element iterators.
         if is_datetimelike(self._values):

pandas/core/dtypes/dtypes.py

@@ -27,6 +27,11 @@ def register_extension_dtype(cls):
     This enables operations like ``.astype(name)`` for the name
     of the ExtensionDtype.
 
+    Returns
+    -------
+    callable
+        A class decorator.
+
     Examples
     --------
     >>> from pandas.api.extensions import register_extension_dtype

pandas/core/dtypes/inference.py

@@ -436,6 +436,10 @@ def is_hashable(obj):
     Distinguish between these and other types by trying the call to hash() and
     seeing if they raise TypeError.
 
+    Returns
+    -------
+    bool
+
     Examples
     --------
     >>> a = ([],)

pandas/core/frame.py

@@ -839,12 +839,12 @@ def itertuples(self, index=True, name="Pandas"):
             The name of the returned namedtuples or None to return regular
             tuples.
 
-        Yields
+        Returns
         -------
-        collections.namedtuple
-            Yields a namedtuple for each row in the DataFrame with the first
-            field possibly being the index and following fields being the
-            column values.
+        iterator
+            An object to iterate over namedtuples for each row in the
+            DataFrame with the first field possibly being the index and
+            following fields being the column values.
 
         See Also
         --------
@@ -1388,6 +1388,10 @@ def to_gbq(self, destination_table, project_id=None, chunksize=None,
             or string contents. This is useful for remote server
             authentication (eg. Jupyter/IPython notebook on remote host).
 
+        Returns
+        -------
+        None
+
         See Also
         --------
         pandas_gbq.to_gbq : This function in the pandas-gbq library.
@@ -3663,6 +3667,10 @@ def lookup(self, row_labels, col_labels):
         col_labels : sequence
             The column labels to use for lookup
 
+        Returns
+        -------
+        numpy.ndarray
+
         Notes
         -----
         Akin to::
@@ -6051,6 +6059,11 @@ def unstack(self, level=-1, fill_value=None):
     col_level : int or string, optional
         If columns are a MultiIndex then use this level to melt.
 
+    Returns
+    -------
+    DataFrame
+        Unpivoted DataFrame.
+
     See Also
     --------
     %(other)s

pandas/core/generic.py

@@ -1518,6 +1518,11 @@ def bool(self):
         This must be a boolean scalar value, either True or False.  Raise a
         ValueError if the PandasObject does not have exactly 1 element, or that
         element is not boolean
+
+        Returns
+        -------
+        bool
+            Same single boolean value converted to bool type.
         """
         v = self.squeeze()
         if isinstance(v, (bool, np.bool_)):
@@ -1845,7 +1850,13 @@ def __hash__(self):
                         ' hashed'.format(self.__class__.__name__))
 
     def __iter__(self):
-        """Iterate over info axis"""
+        """Iterate over info axis.
+
+        Returns
+        -------
+        iterator
+            Info axis as iterator.
+        """
         return iter(self._info_axis)
 
     # can we get a better explanation of this?
@@ -1854,6 +1865,11 @@ def keys(self):
 
         This is index for Series, columns for DataFrame and major_axis for
         Panel.
+
+        Returns
+        -------
+        Index
+            Info axis.
         """
         return self._info_axis
 
@@ -1948,6 +1964,11 @@ def __array_wrap__(self, result, context=None):
     def to_dense(self):
         """
         Return dense representation of NDFrame (as opposed to sparse).
+
+        Returns
+        -------
+        %(klass)s
+            Dense %(klass)s.
         """
         # compat
         return self
@@ -2240,6 +2261,12 @@ def to_json(self, path_or_buf=None, orient=None, date_format=None,
 
             .. versionadded:: 0.23.0
 
+        Returns
+        -------
+        None or str
+            If path_or_buf is None, returns the resulting json format as a
+            string. Otherwise returns None.
+
         See Also
         --------
         read_json
@@ -2364,6 +2391,10 @@ def to_hdf(self, path_or_buf, key, **kwargs):
             See the errors argument for :func:`open` for a full list
             of options.
 
+        Returns
+        -------
+        None
+
         See Also
         --------
         DataFrame.read_hdf : Read from HDF file.
@@ -2420,6 +2451,12 @@ def to_msgpack(self, path_or_buf=None, encoding='utf-8', **kwargs):
             (default is False)
         compress : type of compressor (zlib or blosc), default to None (no
             compression)
+
+        Returns
+        -------
+        None or str
+            If path_or_buf is None, returns the resulting msgpack format as a
+            string. Otherwise returns None.
         """
 
         from pandas.io import packers
@@ -2583,6 +2620,10 @@ def to_pickle(self, path, compression='infer',
             .. [1] https://docs.python.org/3/library/pickle.html
             .. versionadded:: 0.21.0
 
+        Returns
+        -------
+        None
+
         See Also
         --------
         read_pickle : Load pickled pandas object (or any object) from file.
@@ -6171,13 +6212,23 @@ def fillna(self, value=None, method=None, axis=None, inplace=False,
     def ffill(self, axis=None, inplace=False, limit=None, downcast=None):
         """
         Synonym for :meth:`DataFrame.fillna` with ``method='ffill'``.
+
+        Returns
+        -------
+        %(klass)s
+            Object with missing values filled.
         """
         return self.fillna(method='ffill', axis=axis, inplace=inplace,
                            limit=limit, downcast=downcast)
 
     def bfill(self, axis=None, inplace=False, limit=None, downcast=None):
         """
         Synonym for :meth:`DataFrame.fillna` with ``method='bfill'``.
+
+        Returns
+        -------
+        %(klass)s
+            Object with missing values filled.
         """
         return self.fillna(method='bfill', axis=axis, inplace=inplace,
                            limit=limit, downcast=downcast)
@@ -9270,6 +9321,8 @@ def tz_convert(self, tz, axis=0, level=None, copy=True):
 
         Returns
         -------
+        %(klass)s
+            Object with time zone converted axis.
 
         Raises
         ------

pandas/core/groupby/generic.py

@@ -999,6 +999,11 @@ def true_and_notna(x, *args, **kwargs):
     def nunique(self, dropna=True):
         """
         Return number of unique elements in the group.
+
+        Returns
+        -------
+        Series
+            Numver of unique values within each group.
         """
         ids, _, _ = self.grouper.group_info
 
@@ -1181,7 +1186,14 @@ def value_counts(self, normalize=False, sort=True, ascending=False,
         return Series(out, index=mi, name=self._selection_name)
 
     def count(self):
-        """ Compute count of group, excluding missing values """
+        """
+        Compute count of group, excluding missing values.
+
+        Returns
+        -------
+        Series
+            Count of values within each group.
+        """
         ids, _, ngroups = self.grouper.group_info
         val = self.obj.get_values()
 
@@ -1479,7 +1491,14 @@ def _fill(self, direction, limit=None):
         return concat((self._wrap_transformed_output(output), res), axis=1)
 
     def count(self):
-        """ Compute count of group, excluding missing values """
+        """
+        Compute count of group, excluding missing values.
+
+        Returns
+        -------
+        DataFrame
+            Count of values within each group.
+        """
         from pandas.core.dtypes.missing import _isna_ndarraylike as _isna
 
         data, _ = self._get_data_to_aggregate()