API: add 'level' kwarg to 'Index.isin' method by immerrr · Pull Request #7892 · pandas-dev/pandas (original) (raw)

can you follow the numpy docstring format?

Sure, although I thought I was close. What do you think stands out?

It is the exact formatting that is important for the correct rendering (see https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt). It should be formatted as:

(so no blank line, and the explanation should be indented)

I think we should write the docstring for the 'general' case

I was trying to state explicitly that this argument means nothing in particular for simple Index classes while adding a meaningful docstring for MultiIndex.isin, but I do understand that some might like to have it generic and in one place.

The docstring in MultiIndex.isin should also be meaningful. But it is just that in the online documentation, there are references to Index.isin, so I think the all relevant information should also be there (to not have to link to both Index.isin and MultiIndex.isin)

Also, is it stated somewhere that level names must be (or rather, are expected to be) strings?

Ah, no, it can be any object I think, but int and string will be the normal ones?