DOC: update the docstrings of Interval and IntervalMixin
State: closed

Improved the docstrings of Interval (the class) and the following methods
of IntervalMixin:
* closed_right
* closed_left
* open_right
* open_left

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [X] PR title is "DOC: update the <your-function-or-method> docstring"
- [ ] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [X] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [X] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [X] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
######################### Docstring (pandas.Interval)  #########################
################################################################################

Immutable object implementing an Interval, a bounded slice-like interval.

.. versionadded:: 0.20.0

Parameters
----------
left : value
    Left bound for the interval.
right : value
    Right bound for the interval.
closed : {'right', 'left', 'both', 'neither'}, default 'right'
    Whether the interval is closed on the left-side, right-side, both or
    neither.
    A closed interval (in mathematics denoted by square brackets)
    contains the edge points, i.e. the closed interval `[1, 5]` consists
    of the points `1, 2, 3, 4, 5`.
    An open interval (in mathematics denoted by parentheses) does not
    contain the edge points, i.e. the open interval `(1, 5)` consists of
    the points 2, 3, 4.
    Intervals can also be half-open or half closed, i.e.
    `[1,5) = 1, 2, 3, 4` and `(1, 5] = 2, 3, 4, 5`. See also the examples
    section below.

Examples
--------
>>> iv = pd.Interval(left=0, right=5)
>>> iv
Interval(0, 5, closed='right')
>>> 2.5 in iv
True
>>> 0 in iv
False
>>> 5 in iv
True

>>> year_2017 = pd.Interval(pd.Timestamp('2017-01-01'),
...                         pd.Timestamp('2017-12-31'), closed='both')
>>> pd.Timestamp('2017-01-01 00:00') in year_2017
True

See Also
--------
IntervalIndex : An Index of Interval objects that are all closed on the
                same side.
cut : Convert arrays of continuous data into bins of Series/Categoricals
      of Interval.
qcut : Convert arrays of continuous data into bins of Series/Categoricals
       of Interval based on quantiles.

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
        Errors in parameters section
                Unknown parameters {'left', 'right', 'closed'}
        No returns section found
(venv) [akoeltringer@client7 pandas]$ python scripts/validate_docstrings.py pandas.Interval.closed_left

################################################################################
################### Docstring (pandas.Interval.closed_left)  ###################
################################################################################

Check if the interval is closed on the left side.

For the meaning of `closed` and `open` see :class:`~pandas.Interval`.

Returns
-------
bool
    `True` if the Interval is closed on the left-side, else `False`.

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
        See Also section not found
        No examples section found
(venv) [akoeltringer@client7 pandas]$ python scripts/validate_docstrings.py pandas.Interval.closed_right

################################################################################
################### Docstring (pandas.Interval.closed_right) ###################
################################################################################

Check if the interval is closed on the right side.

For the meaning of `closed` and `open` see :class:`~pandas.Interval`.

Returns
-------
bool
    `True` if the Interval is closed on the right-side, else `False`.

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
        See Also section not found
        No examples section found
(venv) [akoeltringer@client7 pandas]$ python scripts/validate_docstrings.py pandas.Interval.open_left

################################################################################
#################### Docstring (pandas.Interval.open_left)  ####################
################################################################################

Check if the interval is open on the left side.

For the meaning of `closed` and `open` see :class:`~pandas.Interval`.

Returns
-------
bool
    `True` if the Interval is open on the left-side, else `False`.

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
        See Also section not found
        No examples section found
(venv) [akoeltringer@client7 pandas]$ python scripts/validate_docstrings.py pandas.Interval.open_right

################################################################################
#################### Docstring (pandas.Interval.open_right) ####################
################################################################################

Check if the interval is open on the right side.

For the meaning of `closed` and `open` see :class:`~pandas.Interval`.

Returns
-------
bool
    `True` if the Interval is open on the right-side, else `False`.

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
        See Also section not found
        No examples section found
```

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

* It is not clear why the error for ``pandas.Interval`` (``Unknown parameters {'left', 'right', 'closed'}``) arises - respondents to this question on Gitter were not sure either
* the ``closed_right``, ``closed_left``, ``open_right`` and ``open_left`` methods have no 'examples' and no 'see also' section because for that the reader is referred to the ``Interval`` class.

Labels:
name: Docs
name: Interval
description: Interval data type

Comments:
Damn, from my phone now, but there is already another open PR. Can you search for that?
So back on laptop now: it is https://github.com/pandas-dev/pandas/pull/20057. Luckily it is not fully overlapping as you also have the attributes. 
Would you like to give feedback on the other PR regarding Interval itself? And then we keep this PR for the attributes. 

Sorry for the overlap! (when assigning I think we forgot the PRs that were already opened by the organisers)
I was also outside so I could not respond earlier. I have to admit that we (PyData Karlsruhe) went a bit 'out of our bounds' - we had the ``Interval.open_*`` and ``Interval.closed_*`` assigned but figured it would be better to document the concepts of openness and closedness once... in ``Interval``...

[#20057](https://github.com/pandas-dev/pandas/pull/20057) has the better docs on the ``left`` and ``right`` parameters, also the examples section seems good. 

Its your decision but you could merge [#20057](https://github.com/pandas-dev/pandas/pull/20057), and then I update my PR based on new master...
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20132?src=pr&el=h1) Report
> Merging [#20132](https://codecov.io/gh/pandas-dev/pandas/pull/20132?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/921fefb319383a561a8829be79972eddebab53c8?src=pr&el=desc) will **decrease** coverage by `0.04%`.
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff             @@
##           master   #20132      +/-   ##
==========================================
- Coverage   91.77%   91.72%   -0.05%     
==========================================
  Files         152      150       -2     
  Lines       49185    49152      -33     
==========================================
- Hits        45140    45086      -54     
- Misses       4045     4066      +21
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.11% <ø> (-0.05%)` | :arrow_down: |
| #single | `41.84% <ø> (-0.01%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20132?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/plotting/\_compat.py](https://codecov.io/gh/pandas-dev/pandas/pull/20132/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb21wYXQucHk=) | `62% <0%> (-28.91%)` | :arrow_down: |
| [pandas/core/arrays/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/20132/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2Jhc2UucHk=) | `74.35% <0%> (-2.39%)` | :arrow_down: |
| [pandas/io/html.py](https://codecov.io/gh/pandas-dev/pandas/pull/20132/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2h0bWwucHk=) | `86.6% <0%> (-2.19%)` | :arrow_down: |
| [pandas/io/formats/format.py](https://codecov.io/gh/pandas-dev/pandas/pull/20132/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvZm9ybWF0LnB5) | `96.26% <0%> (-1.99%)` | :arrow_down: |
| [pandas/core/reshape/melt.py](https://codecov.io/gh/pandas-dev/pandas/pull/20132/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcmVzaGFwZS9tZWx0LnB5) | `97.19% <0%> (-0.15%)` | :arrow_down: |
| [pandas/compat/\_\_init\_\_.py](https://codecov.io/gh/pandas-dev/pandas/pull/20132/diff?src=pr&el=tree#diff-cGFuZGFzL2NvbXBhdC9fX2luaXRfXy5weQ==) | `57.62% <0%> (-0.12%)` | :arrow_down: |
| [pandas/plotting/\_core.py](https://codecov.io/gh/pandas-dev/pandas/pull/20132/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb3JlLnB5) | `82.23% <0%> (-0.04%)` | :arrow_down: |
| [pandas/core/indexes/datetimelike.py](https://codecov.io/gh/pandas-dev/pandas/pull/20132/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZWxpa2UucHk=) | `96.7% <0%> (-0.02%)` | :arrow_down: |
| [pandas/core/ops.py](https://codecov.io/gh/pandas-dev/pandas/pull/20132/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvb3BzLnB5) | `96.33% <0%> (-0.02%)` | :arrow_down: |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/20132/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `95.84% <0%> (-0.02%)` | :arrow_down: |
| ... and [20 more](https://codecov.io/gh/pandas-dev/pandas/pull/20132/diff?src=pr&el=tree-more) | |

------

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

@jschendel Yes you are right. Added a commit.
lgtm

ping @jorisvandenbossche @jreback
@akoeltringer Thanks for the PR!
@jorisvandenbossche thx to you for going the extra mile (merging the conflicting PR)!