DOC: add Raises, Examples and See Also sections to methods at_time/between_time/first/last
State: closed

Added note that methods ``at_time``/``between_time``/``first``/``last`` requires that the index is a DateTimeIndex.

Added functioning examples to the method doc strings.

Added See Also section to the mentioned method doc string.

EDIT: The doc strings for ``DatetimeIndex.indexer_at_time`` and ``DatetimeIndex.indexer_between_time`` said they return a timeseries, while in reality they return arrays. I've corrected that, and made some minor updates to those doc strings in addition.

Labels:
name: Docs
name: Datetime
description: Datetime data dtype

Comments:
The failures are in ``test_parquet`` and ``test_network``, so unrelated to this PR.
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20725?src=pr&el=h1) Report
> Merging [#20725](https://codecov.io/gh/pandas-dev/pandas/pull/20725?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/bd4332f4bff135d4119291f66e98f76cc5f9a80e?src=pr&el=desc) will **increase** coverage by `0.01%`.
> The diff coverage is `100%`.

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

```diff
@@            Coverage Diff             @@
##           master   #20725      +/-   ##
==========================================
+ Coverage   91.81%   91.82%   +0.01%     
==========================================
  Files         153      153              
  Lines       49481    49483       +2     
==========================================
+ Hits        45430    45437       +7     
+ Misses       4051     4046       -5
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.22% <100%> (+0.01%)` | :arrow_up: |
| #single | `41.84% <0%> (-0.01%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20725?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexes/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/20725/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZXMucHk=) | `95.76% <ø> (ø)` | :arrow_up: |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/20725/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `96.12% <100%> (+0.14%)` | :arrow_up: |
| [pandas/util/testing.py](https://codecov.io/gh/pandas-dev/pandas/pull/20725/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvdGVzdGluZy5weQ==) | `84.59% <0%> (+0.2%)` | :arrow_up: |

------

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

Comments from @jschendel have been addressed, thanks for the review.
are these functions in api.rst?
> are these functions in api.rst?

Yes for all of them.
Comments addessed.
Hello @topper-123! Thanks for updating the PR.









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

##### Comment last updated on May 06, 2018 at 12:07 Hours UTC
Comments addressed.
Is this ok, @jreback?

I've added the tests to ``frame/test_timeseries.py`` as discussed above and everything is green.
if anyone has comment: @jorisvandenbossche @TomAugspurger @toobaz otherwise lgtm.
Looks good.

On Mon, May 7, 2018 at 5:29 AM, Jeff Reback <notifications@github.com>
wrote:

> if anyone has comment: @jorisvandenbossche
> <https://github.com/jorisvandenbossche> @TomAugspurger
> <https://github.com/TomAugspurger> @toobaz <https://github.com/toobaz>
> otherwise lgtm.
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> <https://github.com/pandas-dev/pandas/pull/20725#issuecomment-387024929>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/ABQHItvrQkq8pTC54DXy-ewrRM4dyxOgks5twCImgaJpZM4TY95o>
> .
>

thank @topper-123