DOC: Rephrased doc for Series.asof. Added examples
State: closed

Used code from https://github.com/pandas-dev/pandas/issues/20652 as example, to illustrate different behaviours.

- [x] closes #20652
- [x] tests added / passed (N/A, docs)
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry


Labels:
name: Docs

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/21034?src=pr&el=h1) Report
> Merging [#21034](https://codecov.io/gh/pandas-dev/pandas/pull/21034?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/c30c07f765782e11d646baa4a838c9e91c5001af?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `100%`.

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

```diff
@@            Coverage Diff             @@
##           master   #21034      +/-   ##
==========================================
- Coverage   92.23%   92.23%   -0.01%     
==========================================
  Files         161      161              
  Lines       51187    51197      +10     
==========================================
+ Hits        47211    47220       +9     
- Misses       3976     3977       +1
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.61% <100%> (-0.01%)` | :arrow_down: |
| #single | `42.27% <100%> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/21034?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/21034/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `96.81% <100%> (ø)` | :arrow_up: |
| [pandas/core/arrays/timedeltas.py](https://codecov.io/gh/pandas-dev/pandas/pull/21034/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL3RpbWVkZWx0YXMucHk=) | `93.75% <0%> (-0.56%)` | :arrow_down: |
| [pandas/util/testing.py](https://codecov.io/gh/pandas-dev/pandas/pull/21034/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvdGVzdGluZy5weQ==) | `86.64% <0%> (-0.2%)` | :arrow_down: |
| [pandas/core/indexes/api.py](https://codecov.io/gh/pandas-dev/pandas/pull/21034/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9hcGkucHk=) | `99% <0%> (ø)` | :arrow_up: |
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/21034/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `93.87% <0%> (ø)` | :arrow_up: |
| [pandas/core/indexes/datetimelike.py](https://codecov.io/gh/pandas-dev/pandas/pull/21034/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZWxpa2UucHk=) | `98.01% <0%> (ø)` | :arrow_up: |
| [pandas/core/indexes/timedeltas.py](https://codecov.io/gh/pandas-dev/pandas/pull/21034/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy90aW1lZGVsdGFzLnB5) | `90.74% <0%> (+0.12%)` | :arrow_up: |
| [pandas/core/indexes/frozen.py](https://codecov.io/gh/pandas-dev/pandas/pull/21034/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9mcm96ZW4ucHk=) | `92.1% <0%> (+0.43%)` | :arrow_up: |
| [pandas/core/arrays/period.py](https://codecov.io/gh/pandas-dev/pandas/pull/21034/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL3BlcmlvZC5weQ==) | `98.08% <0%> (+0.59%)` | :arrow_up: |

------

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

Hello @dragosthealex! Thanks for updating the PR.



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

##### Comment last updated on May 14, 2018 at 20:44 Hours UTC
@TomAugspurger Yes, the validation passes
can you update for comments
closing as stale. if you'd like to continue pls ping.
@datapythonista this looks close.
Pushed a quick update. Probably good to merge.
thanks @dragosthealex 
Yes, those are good points I wanted to discuss at some point.

This is something I fixed in the past, as the rendering in sphinx was broken:
```
`DataFrame`s -> `DataFrame` objects
```

For what I know, single backticks should be used for argument names, variables, functions, methods, classes... So, `NaN` as a value or concept, could use double backticks, considering it code, normal quotes, or nothing. I don't have a preference.

In the type, we don't usually use backticks (but I've seen some cases where we do):
```
fill_value : object, default None

fill_value : object, default ``None``
```

I don't have a preference either, but we should start to be consistent.

May be we should create an issue, have some discussion, and then start enforcing it? Not sure how difficult can be to add validation for this in `validate_docstrings.py` at this point, but surely something can (and should) be done.