DOC: Improve "inplace" param in Dataframe.rename() docs
State: closed

- [x] closes #23076
- [x] tests added / passed
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry



Labels:
name: Docs
name: DataFrame
description: DataFrame data structure

Comments:
Hello @nmusolino! Thanks for submitting the PR.

 - There are no PEP8 issues in the file [`pandas/core/frame.py`](https://github.com/nmusolino/pandas/blob/f273ef05303797c8992c4402bf1d5e6e18f23daf/pandas/core/frame.py) !

 - There are no PEP8 issues in the file [`pandas/tests/frame/test_alter_axes.py`](https://github.com/nmusolino/pandas/blob/f273ef05303797c8992c4402bf1d5e6e18f23daf/pandas/tests/frame/test_alter_axes.py) !


As described in #23076, the description of "inplace" in the  [current documentation](https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.rename.html) is "backwards".

Arguably, there should be a wider cleanup to use a consistent phrasing for `inplace` across pandas, but the scope of this PR is just fixing the "backwards" parameter documentation in this method.

Here is some prior art for how "inplace" is documented in DataFrame methods with a similar purpose:

[DataFrame.drop()](https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.drop.html)
```
    inplace : bool, default False
        If True, do operation inplace and return None.
```

[DataFrame.reset_index()](https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.reset_index.html)
```
    inplace : boolean, default False
        Modify the DataFrame in place (do not create a new object)
```

[DataFrame.rename_axis()](https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.rename_axis.html#pandas.DataFrame.rename_axis).  This is probably from a shared NDFrame docstring.
```
    inplace : boolean, default False
         Modifies the object directly, instead of creating a new Series or DataFrame.
```



# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24037?src=pr&el=h1) Report
> Merging [#24037](https://codecov.io/gh/pandas-dev/pandas/pull/24037?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/5b0610b875476a6f3727d7e9bedb90d370c669b5?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/24037/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/24037?src=pr&el=tree)

```diff
@@           Coverage Diff           @@
##           master   #24037   +/-   ##
=======================================
  Coverage   42.46%   42.46%           
=======================================
  Files         161      161           
  Lines       51557    51557           
=======================================
  Hits        21892    21892           
  Misses      29665    29665
```

| Flag | Coverage Δ | |
|---|---|---|
| #single | `42.46% <ø> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/24037?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/24037/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `38.7% <ø> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24037?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24037?src=pr&el=footer). Last update [5b0610b...f273ef0](https://codecov.io/gh/pandas-dev/pandas/pull/24037?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24037?src=pr&el=h1) Report
> Merging [#24037](https://codecov.io/gh/pandas-dev/pandas/pull/24037?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/5b0610b875476a6f3727d7e9bedb90d370c669b5?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/24037/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/24037?src=pr&el=tree)

```diff
@@           Coverage Diff           @@
##           master   #24037   +/-   ##
=======================================
  Coverage   42.46%   42.46%           
=======================================
  Files         161      161           
  Lines       51557    51557           
=======================================
  Hits        21892    21892           
  Misses      29665    29665
```

| Flag | Coverage Δ | |
|---|---|---|
| #single | `42.46% <ø> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/24037?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/24037/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `38.7% <ø> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24037?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24037?src=pr&el=footer). Last update [5b0610b...f273ef0](https://codecov.io/gh/pandas-dev/pandas/pull/24037?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

> Arguably, there should be a wider cleanup to use a consistent phrasing for inplace across pandas

That sounds like a plan.  Maybe we could do it in this PR even.
I'm willing to work on that in a future PR.  My suggestion is to get this PR in right now, in order to fix the mistaken docstring and close the associated issue (#23076).

The problem with the current `DataFrame.rename()` docstring, just to be explicit, is this:  in general, when a parameter \<X\> has a description "whether to \<blank\>", the implication is that when the parameter X is true, the method will "\<blank\>".  

The current docstring does not follow that convention, and in fact inverts that convention.

As for the wider change, I think that will take more discussion:

1.  How should the parameter description be phrased?
2.  Should the "Returns" section of each method include a note about returning None when inplace is True (where applicable)?
3.  Should the parameter description mention that internal data structures (e.g. block manager or index) might be copied even when inplace is True?

Or even, should that effort be made in light of #16529: [API/DEPR: Deprecate inplace parameter](https://github.com/pandas-dev/pandas/issues/16529)?  I just saw that deprecation proposal now.
cc @datapythonista 
Closing in favor of #24063, where the `inplace` argument will be deprecated, and all descriptions updated.