DOC: Updating pandas.Interval docstring
State: closed

Docstring assigned to the Buenos Aires chapter for the sprint.

Hi, I have a few doubts about the changes.

First about the type of the parameters *left* and *right*, it's ok to refer to them as *orderable*?
In the implementation, the constructor takes any pair of objects that satisfy `left <= right` and the comparison returns a boolean value.
 I tried to pass two numpy arrays and it breaks because of ambiguity, but still it's so general that you can even make Intervals of Intervals, sets or booleans. And I believe this is too permissive and prone to error. 

So what it's better, put a warning about this or add an example that is a little more complex and uses this capability (I tried to think one, but nothing came up to my mind).

And last,  validate_docstrings.py returned this error

`2341, in _signature_from_callable 
   'no signature found for builtin type {!r}'.format(obj)) 
ValueError: no signature found for builtin type <class 'pandas._libs.interval.Interval'>
`

Thanks, happy to collaborate.

PS: Given that this is a Cython file I needed to recompile the project to see the changes in the documentation. I mention this because is not in the sprint guide and I don't know if I will able to add it before the event.

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

Comments:
> And last, validate_docstrings.py returned this error
> 
> 2341, in _signature_from_callable 'no signature found for builtin type {!r}'.format(obj)) ValueError: no signature found for builtin type <class 'pandas._libs.interval.Interval'>

Can you try the latest version? I think this should be fixed now. 
You can update this branch by doing:

```
git fetch upstream
git merge upstream/master
```

and then try the script again.

> Given that this is a Cython file I needed to recompile the project to see the changes in the documentation. I mention this because is not in the sprint guide and I don't know if I will able to add it before the event.

Ah, indeed, that's a good catch. That's something we need to add to the guide.

> So what it's better, put a warning about this or add an example that is a little more complex and uses this capability (I tried to think one, but nothing came up to my mind).

I would personally give 'good examples', as you did now. And the note you added about `left <= right` needing to work seems sufficient to me.
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20057?src=pr&el=h1) Report
> Merging [#20057](https://codecov.io/gh/pandas-dev/pandas/pull/20057?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/df2e361b899d445fe71d4a9188c546f593251cea?src=pr&el=desc) will **increase** coverage by `0.02%`.
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff             @@
##           master   #20057      +/-   ##
==========================================
+ Coverage    91.7%   91.73%   +0.02%     
==========================================
  Files         150      150              
  Lines       49168    49168              
==========================================
+ Hits        45090    45102      +12     
+ Misses       4078     4066      -12
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.11% <ø> (+0.02%)` | :arrow_up: |
| #single | `41.86% <ø> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20057?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/plotting/\_converter.py](https://codecov.io/gh/pandas-dev/pandas/pull/20057/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb252ZXJ0ZXIucHk=) | `66.81% <0%> (+1.73%)` | :arrow_up: |

------

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

Thanks for the comments, I tried to improve it following your guidelines.
@jschendel could you give this another look?
@akielbowicz Thanks a lot!