DOC: Add examples to .get_loc methods
State: closed

- [ x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`

This pull request adds some examples to ``.get_loc`` doc string of ``pd.Index``, ``pd.CategoricalIndex``, ``pd.MultiIndex`` & ``pd.IntervalIndex``. Also clarifies the return value in some cases.

I previously proposed pull request #17380, but the commit history there became a mess. I've deleted that pull request and added this instead.

Labels:
name: Docs
name: Indexing
description: Related to indexing on series/frames, not to indexes themselves

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

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

```diff
@@            Coverage Diff             @@
##           master   #17563      +/-   ##
==========================================
- Coverage   91.25%   91.23%   -0.02%     
==========================================
  Files         163      163              
  Lines       49617    49617              
==========================================
- Hits        45277    45268       -9     
- Misses       4340     4349       +9
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `89.02% <100%> (ø)` | :arrow_up: |
| #single | `40.19% <100%> (-0.07%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexes/multi.py](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9tdWx0aS5weQ==) | `96.9% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/interval.py](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9pbnRlcnZhbC5weQ==) | `93.57% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/category.py](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9jYXRlZ29yeS5weQ==) | `98.55% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9iYXNlLnB5) | `96.28% <100%> (ø)` | :arrow_up: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <0%> (-58.34%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.77% <0%> (-0.1%)` | :arrow_down: |

------

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

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

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

```diff
@@            Coverage Diff             @@
##           master   #17563      +/-   ##
==========================================
- Coverage   91.25%   91.23%   -0.02%     
==========================================
  Files         163      163              
  Lines       49617    49617              
==========================================
- Hits        45277    45268       -9     
- Misses       4340     4349       +9
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `89.02% <100%> (ø)` | :arrow_up: |
| #single | `40.19% <100%> (-0.07%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexes/interval.py](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9pbnRlcnZhbC5weQ==) | `93.57% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/multi.py](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9tdWx0aS5weQ==) | `96.9% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/category.py](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9jYXRlZ29yeS5weQ==) | `98.55% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9iYXNlLnB5) | `96.28% <100%> (ø)` | :arrow_up: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <0%> (-58.34%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.77% <0%> (-0.1%)` | :arrow_down: |

------

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

# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=h1) Report
> Merging [#17563](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/b59f107a529ac9b1e2859217ea58f7e26b6749d0?src=pr&el=desc) will **decrease** coverage by `0.01%`.
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff             @@
##           master   #17563      +/-   ##
==========================================
- Coverage   91.19%   91.18%   -0.02%     
==========================================
  Files         163      163              
  Lines       49626    49626              
==========================================
- Hits        45258    45249       -9     
- Misses       4368     4377       +9
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `88.96% <ø> (ø)` | :arrow_up: |
| #single | `40.19% <ø> (-0.07%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexes/category.py](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9jYXRlZ29yeS5weQ==) | `98.55% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9iYXNlLnB5) | `96.28% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/multi.py](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9tdWx0aS5weQ==) | `96.9% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/interval.py](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9pbnRlcnZhbC5weQ==) | `93.57% <ø> (ø)` | :arrow_up: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <0%> (-58.34%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/17563?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.77% <0%> (-0.1%)` | :arrow_down: |

------

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

I think you still need to use the ``@Appender`` of the shared docs, then add the examples
Hello @topper-123! Thanks for updating the PR.









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

##### Comment last updated on September 20, 2017 at 14:58 Hours UTC
I've made various changes.The @Appender is still there, though the examples are in it as well.

The ``.get_loc`` methods are subtly differerent for the differerent index types, so I think it will be difficult to get real doc reuse, though.

EDIT: Are you sure it's ok to force-push changes to the same commit? To me it seems that it makes reviewting more difficult, as the connection between code and comments seems to get lost.
The error is at ``pandas/tests/io/parser/test_network.py:74``. with error message: ``HTTPError: HTTP Error 504: Gateway Time-out``.

So the error seems to be unrelated to my pull request...
> EDIT: Are you sure it's ok to force-push changes to the same commit? To me it seems that it makes reviewting more difficult, as the connection between code and comments seems to get lost.

if commits are logical / organized and have good messages, yes. however most commits I see should just be combined into 1 and promote even more confusion. rebasing is also much easier with fewer commits. so force pushing is fine as its your own fork. 
looks fine. can you rebase and push again to force ci to run.
> EDIT: Are you sure it's ok to force-push changes to the same commit? To me it seems that it makes reviewting more difficult, as the connection between code and comments seems to get lost.

For that reason in general I prefer to add commits instead of rebasing/force push, but to clean up messed up github state, it is perfectly fine (as long as it is in a branch).
Green @jreback 
@topper-123 Thanks!