DOC: improve binary operator docs (fixes #10093)

[mortada]

fixes #10093

@jorisvandenbossche this covers Series, DataFrame and Panel, please take a look

[jorisvandenbossche]

The resulting text would now be: Binary operator subtraction.

I think that maybe also the 'binary operator' part can be confusing for people. I don't know if this terminology is that familiar for most users?
Thinking about an alternative, I came up with Subtraction of series and other (binary operator ``sub``).

[mortada]

actually the current implementation is such that the doc would be: Binary operator sub (subtraction)

[jorisvandenbossche]

Ah, yes, I see the desc line!
But still, my reservation about 'binary operator' stays the same (but to be clear, just adding the full name between parantheses is already a big improvement)

[mortada]

hmm... yeah the wording for this is kind of tricky

[mortada]

if we go with Subtraction of series and other (binary operator sub) maybe it should be Subtraction of other from series instead to indicate the order of operation, and so rsub would be Subtraction of series from other. But I'm not sure if this is actually more clear.

[jorisvandenbossche]

Proposal:

Subtraction of series and other, element-wise (binary operator `sub`).

Equivalent to ``series - other``, but with support to substitute a fill_value for missing data in
one of the inputs.

But agree that the "series and other" is maybe better as "other from series", but that will depend a bit from operator to operator how to best specify it.

Can you maybe also add a 'see also' section each time to the reversed/non-reversed version (add -> radd, radd -> add, ...)

[mortada]

So I ended up restructuring the code quite a bit in order to pack more information into the docstring, also added a unit test for it. Please take a look.

Basically the docstrings look like this now:

Signature: pd.DataFrame.sub(self, other, axis='columns', level=None, fill_value=None)
Docstring:
Subtraction of dataframe and other, element-wise (binary operator `-`).

Equivalent to ``dataframe - other``, but with support to substitute a fill_value for
missing data in one of the inputs.

Parameters
----------
other : Series, DataFrame, or constant
axis : {0, 1, 'index', 'columns'}
    For Series input, axis to match Series index on
fill_value : None or float value, default None
    Fill missing (NaN) values with this value. If both DataFrame locations are
    missing, the result will be missing
level : int or name
    Broadcast across a level, matching Index values on the
    passed MultiIndex level

Notes
-----
Mismatched indices will be unioned together

Returns
-------
result : DataFrame

See also
--------
DataFrame.rsub

[jorisvandenbossche]

Nice! Thanks a lot.

[mortada]

Noticed a small problem, instead of:
element-wise (binary operator -)
we should have:
element-wise (binary operator sub)

it's fixed now

[jorisvandenbossche]

Travis is failing, but seems to be related to another issue

[jreback]

yep will be fixed by #10152

[jorisvandenbossche]

OK, merging then. @mortada Thanks a lot!