Fix docstrings, error messages
State: closed

The discussion in #19558 makes me think getting PeriodArray and DatetimeArray implemented sooner rather than later will make things easier for other goals.  In preparation for that, this PR goes through (most) of the methods that will need to be ported and adapts their error messages to be class-agnostic, and to use `str.format` syntax.

Also fixes a couple of copy/paste typos in docstrings.

Labels:
name: Docs
name: Error Reporting
description: Incorrect or improved errors from pandas
name: Internals
description: Related to non-user accessible pandas implementation

Comments:
Haven't looked closely yet, but I haven't touched datetimeindex yet.

Including the correct class name in the error message has been an issue, so those changes should be worthwhile.

Should be able to look closer in a few days.
Just pushed a fix for the `shift` docstring that re-evaluates it within `TimedeltaIndex` and `DatetimeIndex`.  I'm wondering if there is a metaclass (or hopefully a lighter-weight option) way to do this without having to re-define the function in each subclass.  Could that be what `_decorators.docstring_wrapper` (which is not used) is for?
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/19672?src=pr&el=h1) Report
> Merging [#19672](https://codecov.io/gh/pandas-dev/pandas/pull/19672?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/2fdf1e256e5e0b7f1fe909629e2f0b7893c8c7c3?src=pr&el=desc) will **increase** coverage by `<.01%`.
> The diff coverage is `93.1%`.

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

```diff
@@            Coverage Diff             @@
##           master   #19672      +/-   ##
==========================================
+ Coverage   91.58%   91.58%   +<.01%     
==========================================
  Files         150      150              
  Lines       48867    48875       +8     
==========================================
+ Hits        44755    44763       +8     
  Misses       4112     4112
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `89.96% <93.1%> (ø)` | :arrow_up: |
| #single | `41.75% <41.37%> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/19672?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexes/datetimelike.py](https://codecov.io/gh/pandas-dev/pandas/pull/19672/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZWxpa2UucHk=) | `97.05% <100%> (ø)` | :arrow_up: |
| [pandas/core/indexes/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/19672/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZXMucHk=) | `95.33% <90.9%> (+0.01%)` | :arrow_up: |
| [pandas/core/indexes/timedeltas.py](https://codecov.io/gh/pandas-dev/pandas/pull/19672/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy90aW1lZGVsdGFzLnB5) | `90.63% <93.33%> (+0.07%)` | :arrow_up: |

------

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

Thoughts on this?  There are a number of broken cases to fix in and around these methods; ideally we'd close this out first.