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

Hello @matagus! Thanks for updating the PR.



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

##### Comment last updated on August 21, 2017 at 08:25 Hours UTC # [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/16948?src=pr&el=h1) Report
> :exclamation: No coverage uploaded for pull request base (`master@91245a7`). [Click here to learn what that means](https://docs.codecov.io/docs/error-reference#section-missing-base-commit).
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff            @@
##             master   #16948   +/-   ##
=========================================
  Coverage          ?   91.01%           
=========================================
  Files             ?      162           
  Lines             ?    49567           
  Branches          ?        0           
=========================================
  Hits              ?    45114           
  Misses            ?     4453           
  Partials          ?        0
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `88.79% <ø> (?)` | |
| #single | `40.24% <ø> (?)` | |

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

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/16948?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/16948?src=pr&el=footer). Last update [91245a7...0a07775](https://codecov.io/gh/pandas-dev/pandas/pull/16948?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).
 can you update @matagus Do you have time to update this according to the feedback? 
(if not, no problem, but please indicate this so somebody else can take over) @gfyoung if you have a chance can you fix up. @jreback : Changes requested have been addressed.  PTAL. Thanks @matagus and @gfyoung !

(btw, @gfyoung I personally find it easier that you add commits instead of amending the previous one, it's sometimes easier to see what has changes (in this case only small diff, so not really a problem, but for larger diffs can be helpful) @jorisvandenbossche : Absolutely.  Good to know.

On a separate note, what is the purpose of the `convert` parameter (I generally don't use it)?  I see no difference in behavior AFAICT (using the docstring example):

~~~python
>>> df.take([-1, -2])
             name   class  max_speed
        1  monkey  mammal        NaN
        3    lion  mammal       80.5
>>> df.take([-1, -2], convert=False)
             name   class  max_speed
        1  monkey  mammal        NaN
        3    lion  mammal       80.5
~~~ Good catch, reason is very simple, it is not passed through:

https://github.com/pandas-dev/pandas/blob/d0d28fec180ee61de17921fe5068ecde95adae8a/pandas/core/generic.py#L2140-L2142

But not sure if this should actually be a public parameter

 Doh!  Yeah, that's a good point.  Drilling further down reveals more strangeness:

https://github.com/pandas-dev/pandas/blob/d0d28fec180ee61de17921fe5068ecde95adae8a/pandas/core/internals.py#L4096-L4099

The error message doesn't seem to match the check here IINM.