DOC: update doc-string in Index.rename
State: closed

updated doc-strings with examples 
- [x] closes #20787
- N/A tests added / passed
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- N/A whatsnew entry


Labels:
name: Docs

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/22363?src=pr&el=h1) Report
> Merging [#22363](https://codecov.io/gh/pandas-dev/pandas/pull/22363?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/8bb2cc19ca3aa347d086b4fb5704ca9a3723172f?src=pr&el=desc) will **increase** coverage by `<.01%`.
> The diff coverage is `100%`.

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

```diff
@@            Coverage Diff             @@
##           master   #22363      +/-   ##
==========================================
+ Coverage   92.05%   92.05%   +<.01%     
==========================================
  Files         169      169              
  Lines       50713    50714       +1     
==========================================
+ Hits        46683    46684       +1     
  Misses       4030     4030
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.46% <100%> (ø)` | :arrow_up: |
| #single | `42.25% <0%> (-0.01%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/22363?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexes/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/22363/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9iYXNlLnB5) | `96.43% <100%> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/22363?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/22363?src=pr&el=footer). Last update [8bb2cc1...401e6b2](https://codecov.io/gh/pandas-dev/pandas/pull/22363?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

I fixed some details in `Index.rename` and `Index.set_names`

```python
################################################################################
####################### Docstring (pandas.Index.rename)  #######################
################################################################################

Set new names on index. Defaults to returning new index.

Length of names must match number of levels in MultiIndex.

Parameters
----------
name : str or list
    Name(s) to set.
inplace : bool
    If True, mutates in place.

Returns
-------
new index (of same type and class...etc) [if inplace, returns None]

Examples
--------
>>> idx = pd.Index([1, 2, 3, 4], name='foo')
>>> idx.rename('bar')
Int64Index([1, 2, 3, 4], dtype='int64', name='bar')

>>> idx = pd.MultiIndex.from_tuples([(1, u'one'), (1, u'two'),
...                                  (2, u'one'), (2, u'two')],
...                                  names=['foo', 'bar'])
>>> idx.rename(['bar', None])
MultiIndex(levels=[[1, 2], ['one', 'two']],
           labels=[[0, 0, 1, 1], [0, 1, 0, 1]],
           names=['bar', None])
>>> idx.rename(['bar'])
Traceback (most recent call last):
ValueError: Length of names must match number of levels in MultiIndex.

See also
--------
set_names : able to set new names partially and by level

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.Index.rename" correct. :)
```

```python
################################################################################
###################### Docstring (pandas.Index.set_names) ######################
################################################################################

Set new names on index. Defaults to returning new index.

Parameters
----------
names : str or sequence
    Name(s) to set.
level : int, level name, or sequence of int/level names (default None)
    If the index is a MultiIndex (hierarchical), level(s) to set (None
    for all levels).  Otherwise level must be None.
inplace : bool
    If True, mutates in place.

Returns
-------
new index (of same type and class...etc) [if inplace, returns None]

Examples
--------
>>> pd.Index([1, 2, 3, 4]).set_names('foo')
Int64Index([1, 2, 3, 4], dtype='int64', name='foo')
>>> pd.Index([1, 2, 3, 4]).set_names(['foo'])
Int64Index([1, 2, 3, 4], dtype='int64', name='foo')

>>> idx = pd.MultiIndex.from_tuples([(1, u'one'), (1, u'two'),
...                                  (2, u'one'), (2, u'two')],
...                                  names=['foo', 'bar'])
>>> idx.set_names(['baz', 'quz'])
MultiIndex(levels=[[1, 2], ['one', 'two']],
           labels=[[0, 0, 1, 1], [0, 1, 0, 1]],
           names=['baz', 'quz'])
>>> idx.set_names('baz', level=0)
MultiIndex(levels=[[1, 2], ['one', 'two']],
           labels=[[0, 0, 1, 1], [0, 1, 0, 1]],
           names=['baz', 'bar'])

See also
--------
rename : able to set new names without level

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	No extended summary found
```
I fixed detailed you said. and I changed one error msg to a proper one. 
And I got one question. 

now `Index.rename` get `level` parameter just `like set_names`. 
```python
>>> idx = pd.MultiIndex.from_tuples([(1, 'one'), (1, 'two'),
...                                  (2, 'one'), (2, 'two')],
...                                  names=['foo', 'bar'])
>>> idx.rename(1, level=0)
MultiIndex(levels=[[1, 2], ['one', 'two']],
           labels=[[0, 0, 1, 1], [0, 1, 0, 1]],
           names=[1, 'bar'])
```
should we prevent rename from getting level parameter?
Hello @Moons08! Thanks for updating the PR.





Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on August 19, 2018 at 09:59 Hours UTC
Thanks @Moons08, very good work, very clear docstring.