Unclear documentation of inplace parameter for pandas.DataFrame.rename.

[antomaly]

Problem description

The documentation for pandas.DataFrame.rename currently reads

inplace : boolean, default False

Whether to return a new DataFrame. If True then value of copy is ignored.

The sentence "Whether to return a new DataFrame" suggests that setting this parameter to True means a new DataFrame will be returned. The parameter name "inplace" suggests that setting this parameter to True means a new DataFrame will not be returned, which is actually the case.

The only thing in the documentation which concretely specifies the true behavior is the parameter name.

A possible alternate phrasing which suggests the correct thing would be to replace the sentence "Whether to return a new DataFrame" with something like "Modify the DataFrame, instead of returning a new DataFrame."

Same thing for the base class NDFrame and its other derived classes like Panel.

[WillAyd]

Makes sense - PRs to improve documentation are always welcome

[Carla08]

Is anyone working on this already? I'd like to take this as my first issue.

[nmusolino]

I very much agree with the original description that the "sense" of the parameter's documentation is wrong. I created a PR (#24037) with an attempt at fixing this, while being somewhat consistent with other "inplace" documentation.

[datapythonista]

Closing in favor of #24063, where the inplace argument will be deprecated, and all descriptions updated.