DOC: updating docstring of Index.shift
State: closed

Docstring assigned to PyData Budapest chapter of the Worldwide Documentation Sprint.

As Index.shift is an abstract method, this is more of a docstring for developers implementing a subclass than for end users.

Labels:
name: Docs

Comments:
@DataOmbudsman btw, thanks a lot for the PR! You are a bit unlucky that this one is not fully clear what should be done with it (although there will be many like that during the sprint as well). 
One thing we can do is write this docstring fully complete for users, and then reuse the docstring for `Datetime/Period/TimedeltaIndex.shift`. You could do this by using the `@Appender` decorator
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/19996?src=pr&el=h1) Report
> :exclamation: No coverage uploaded for pull request base (`master@aedbd94`). [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/19996/graphs/tree.svg?height=150&src=pr&token=eZ4WkYLtcO&width=650)](https://codecov.io/gh/pandas-dev/pandas/pull/19996?src=pr&el=tree)

```diff
@@            Coverage Diff            @@
##             master   #19996   +/-   ##
=========================================
  Coverage          ?   91.64%           
=========================================
  Files             ?      150           
  Lines             ?    49096           
  Branches          ?        0           
=========================================
  Hits              ?    44995           
  Misses            ?     4101           
  Partials          ?        0
```

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

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

------

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

@jorisvandenbossche Thanks for your notes. I understand your points. When discussing this issue in the sprint mailing list my interpretation of the answer by @datapythonista was that pandas developers are the target audience of this specific docstring rather than pandas users. Maybe I misunderstood it but it seemed reasonable since it was hard for me to imagine a pandas user browsing the docstring of this abstract function.

I've been reluctant to include a Returns section since what this method returns is specified in subclasses that implement this method. I avoided the Examples for the same reason -- how can I give examples of an abstract method that doesn't implement anything? 

Nevertheless, your idea about making this docstring fully complete for users, and then reuse it for `Datetime/Period/TimedeltaIndex.shift` is also reasonable, I will look into `@Appender`.

> Maybe I misunderstood it but it seemed reasonable since it was hard for me to imagine a pandas user browsing the docstring of this abstract function.

This is the docstring that is included in the online API docs. So if somebody searches for "pandas index shift", it will end up there. So even if the method itself is not implemented in the base class, the docstring should be targeted to users IMO.

> I will look into @Appender.

It should be something like

```
class DatetimeIndex

    ....

    @Appender(ibase.Index.shift.__doc__)
    def shift(...):
        ....
```

Reusing the docstring of `Index.shift` is pretty tricky, so I would leave that out of scope if that's acceptable. For example it should handle that parameter names and number of parameters change in the subclasses. The Returns and Notes sections should be changed in the subclasses.
@jorisvandenbossche if you'd approve the PRs then easy to see what to merge :> (or just give a lgtm).
thanks!