Description
Location of the documentation
This proposal concerns all methods with the inplace keyword argument. Three examples:
1 (Return type described as "blah-blah-type or None if inplace=True) https://pandas.pydata.org/docs/dev/reference/api/pandas.CategoricalIndex.add_categories.html?highlight=inplace
2 (Return type specified, but doesn't mention None) https://pandas.pydata.org/docs/dev/reference/api/pandas.Series.interpolate.html?highlight=inplace
Documentation problem
Many methods in pandas have keyword argument inplace. When inplace=True is supplied, the method updates self and returns None. When inplace=False is supplied, the method does not affect self and returns a changed copy of self.
Some of these functions' return types are documented as "Returns blah-type if inplace=True". Others just say "Returns blah-type". This is confusing because it suggests inconsistencies in behavior that are not really there.
Suggested fix for documentation
Find all methods with the inplace keyword argument. Change the "returns" section of their docstrings to this form:
Returns
-------
Series or DataFrame
Returns the same object type as the caller, interpolated at
some or all ``NaN`` values. (Or return `None` if
`inplace=True`.)
Also change all the formal return type signatures to the form "--> Optional[Foo]" if they aren't all already like that.