DOC: add versionadded specifications to docstrings

[jorisvandenbossche]

We already use the .. versionadded:: directive in the tutorial docs to indicate that a certain feature is only present starting from a specific pandas version.
But I propose that we also start to do this in the docstrings, when adding a new function/method or adding a new keyword to an existing function/method:

• When developing a package depending on pandas, you typically are using latest pandas but want to support also certain older versions. When using a certain method/function/keyword functionality, the easiest place to see if this is available is the docstring.
• Or, you also typically look at the stable docs even when using a maybe older pandas version and see functions/keywords that don't yet exist for your version.
• This is also how it is done in numpy:
  • example of new method: http://docs.scipy.org/doc/numpy-dev/reference/generated/numpy.nanmean.html
  • example of new keyword: http://docs.scipy.org/doc/numpy-dev/reference/generated/numpy.percentile.html

So if we agree on this, some todo's:

• add guidelines to the developer docs on how to add this (and start asking for this when reviewing PRs)
• - optional - add this retrospectively to eg the new features of 0.16.0/1 (DOC: add versionadded to docstrings for 0.16.0 / 0.16.1 #10339 for 0.16.0/0.16.1)

[jorisvandenbossche]

@jreback @shoyer @sinhrks @TomAugspurger

Any objections to this?
It would look something like this: jorisvandenbossche@274826e

[TomAugspurger]

👍

[jreback]

lgtm

[sinhrks]

Nice, will do.

[shoyer]

Agreed, seems like a good idea.