DOC: make return type documentation of series methods consistent pandas-dev#35409

Author: junjunjunk

pandas/core/arrays/categorical.py

@@ -723,8 +723,8 @@ def as_ordered(self, inplace=False):
 
         Returns
         -------
-        Categorical
-            Ordered Categorical.
+        Categorical or None
+            Ordered Categorical or None if ``inplace=True``.
         """
         inplace = validate_bool_kwarg(inplace, "inplace")
         return self.set_ordered(True, inplace=inplace)
@@ -741,8 +741,8 @@ def as_unordered(self, inplace=False):
 
         Returns
         -------
-        Categorical
-            Unordered Categorical.
+        Categorical or None
+            Unordered Categorical or None if ``inplace=True``.
         """
         inplace = validate_bool_kwarg(inplace, "inplace")
         return self.set_ordered(False, inplace=inplace)
@@ -848,8 +848,7 @@ def rename_categories(self, new_categories, inplace=False):
         Returns
         -------
         cat : Categorical or None
-           With ``inplace=False``, the new categorical is returned.
-           With ``inplace=True``, there is no return value.
+            Categorical with removed categories or None if ``inplace=True``.
 
         Raises
         ------
@@ -917,7 +916,8 @@ def reorder_categories(self, new_categories, ordered=None, inplace=False):
 
         Returns
         -------
-        cat : Categorical with reordered categories or None if inplace.
+        cat : Categprocal or None
+            Categorical with removed categories or None if ``inplace=True``.
 
         Raises
         ------
@@ -957,7 +957,8 @@ def add_categories(self, new_categories, inplace=False):
 
         Returns
         -------
-        cat : Categorical with new categories added or None if inplace.
+        cat : Categorical or None
+            Categorical with new categories added or None if ``inplace=True``.
 
         Raises
         ------
@@ -1007,7 +1008,8 @@ def remove_categories(self, removals, inplace=False):
 
         Returns
         -------
-        cat : Categorical with removed categories or None if inplace.
+        cat : Categorical or None
+            Categorical with removed categories or None if ``inplace=True``.
 
         Raises
         ------
@@ -1054,7 +1056,8 @@ def remove_unused_categories(self, inplace=False):
 
         Returns
         -------
-        cat : Categorical with unused categories dropped or None if inplace.
+        cat : Categorical or None
+            Categorical with unused categories dropped or None if ``inplace=True``.
 
         See Also
         --------

pandas/core/generic.py

@@ -649,7 +649,7 @@ def set_axis(self, labels, axis: Axis = 0, inplace: bool = False):
         Returns
         -------
         renamed : %(klass)s or None
-            An object of type %(klass)s if inplace=False, None otherwise.
+            An object of type %(klass)s or None if ``inplace=True``.
 
         See Also
         --------
@@ -1096,7 +1096,7 @@ def rename_axis(self, mapper=lib.no_default, **kwargs):
         Returns
         -------
         Series, DataFrame, or None
-            The same type as the caller or None if `inplace` is True.
+            The same type as the caller or None if ``inplace=True``.
 
         See Also
         --------
@@ -6461,8 +6461,8 @@ def replace(
 
         Returns
         -------
-        {klass}
-            Object after replacement.
+        {klass} or None
+            Object after replacement or None if ``inplace=True``.
 
         Raises
         ------
@@ -6896,9 +6896,9 @@ def interpolate(
 
         Returns
         -------
-        Series or DataFrame
+        Series or DataFrame or None
             Returns the same object type as the caller, interpolated at
-            some or all ``NaN`` values.
+            some or all ``NaN`` values
 
         See Also
         --------
@@ -7494,9 +7494,9 @@ def clip(
 
         Returns
         -------
-        Series or DataFrame
+        Series or DataFrame or None
             Same type as calling object with the values outside the
-            clip boundaries replaced.
+            clip boundaries replaced or None if ``inplace=True``.
 
         See Also
         --------
@@ -9048,9 +9048,9 @@ def where(
         try_cast : bool, default False
             Try to cast the result back to the input type (if possible).
 
-        Returns
+        Returns or None
         -------
-        Same type as caller
+        Same type as caller or None if ``inplace=True``.
 
         See Also
         --------

pandas/core/series.py

@@ -1192,7 +1192,7 @@ def reset_index(self, level=None, drop=False, name=None, inplace=False):
 
         Returns
         -------
-        Series or DataFrame
+        Series or DataFrame or None
             When `drop` is False (the default), a DataFrame is returned.
             The newly created columns will come first in the DataFrame,
             followed by the original Series values.
@@ -1911,8 +1911,8 @@ def drop_duplicates(self, keep="first", inplace=False) -> Optional["Series"]:
 
         Returns
         -------
-        Series
-            Series with duplicates dropped.
+        Series or None
+            Series with duplicates dropped or None if ``inplace=True``.
 
         See Also
         --------
@@ -3129,8 +3129,8 @@ def sort_values(
 
         Returns
         -------
-        Series
-            Series ordered by values.
+        Series or None
+            Series ordered by values or None if ``inplace=True``.
 
         See Also
         --------
@@ -3375,8 +3375,8 @@ def sort_index(
 
         Returns
         -------
-        Series
-            The original Series sorted by the labels.
+        Series or None
+            The original Series sorted by the labels or None if ``inplace=True``.
 
         See Also
         --------
@@ -4304,8 +4304,8 @@ def rename(
 
         Returns
         -------
-        Series
-            Series with index labels or name altered.
+        Series or None
+            Series with index labels or name altered
 
         See Also
         --------
@@ -4418,8 +4418,8 @@ def drop(
 
         Returns
         -------
-        Series
-            Series with specified index labels removed.
+        Series or None
+            Series with specified index labels removed or None if ``inplace=True``.
 
         Raises
         ------
@@ -4807,8 +4807,8 @@ def dropna(self, axis=0, inplace=False, how=None):
 
         Returns
         -------
-        Series
-            Series with NA entries dropped from it.
+        Series or None
+            Series with NA entries dropped from it or None if ``inplace=True``.
 
         See Also
         --------