DOC: Improving docstring of reset_index method (#16416)
 - [ ] closes #xxxx
 - [ ] tests added / passed
 - [ ] passes ``git diff upstream/master -u -- "*.py" | flake8 --diff``
 - [ ] whatsnew entry

I failed to see that someone else was taking care of the reset_index documentation. But I think the examples I implemented are more clear, so submitting the PR anyway.
Hello @datapythonista! Thanks for updating the PR.



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

##### Comment last updated on July 18, 2017 at 16:55 Hours UTC @gfyoung does it look all right the PR after addressing all the comments in your review? @datapythonista : Thanks for pinging me!  The documentation looks better now.  A few more things to address, and I think this will be ready. Added the ticks, thanks for the heads up @gfyoung .

To add the example you mention, we should add another level to the example. And it'd probably start to look too complex to follow it easily. I'd leave that for another PR, where we can see if it's adding value, or making things too complex. > To add the example you mention, we should add another level to the example. And it'd probably start to look too complex to follow it easily.

Agreed.  What I would do is create an entirely different object (i.e. `DataFrame`) for addressing `col_fill` so that the examples you provided earlier don't need to change.  How does that sound? Honestly, I think it's too much.

This method didn't have any example couple of days ago. As it's the case for most of pandas methods. This PR adds examples for each of the parameters, and it already needs to define two different dataframes. To me it's already quite clear what `col_fill` does, in the two different cases it can be used with (an existing level, and a new level). Even if just one of them got an explicit example.

I'd rather prefer to work in other methods with very poor documentation, than trying to make `reset_index`have a pseudo-perfect documentation. > To me it's already quite clear what col_fill does, in the two different cases it can be used with (an existing level, and a new level). Even if just one of them got an explicit example.

We're trying to ensure that this documentation is as clear as we can make it for everyone, even if we ourselves find it clear already.  I understand that adding another example might be more complicated.  However, I'm just trying to help this PR get to state where I feel comfortable merging this.

> I'd rather prefer to work in other methods with very poor documentation, than trying to make `reset_index` have a pseudo-perfect documentation.

That's fair, though I also presume you would like this merged too.  Why don't I bring @jreback into this conversation and see what he thinks is best in terms of resolving this impasse. agree that better to have *some* examples in very used functions than going crazy on one :<

thanks @datapythonista 

keep em coming! Thanks a lot for it @jreback 