docs: clarify type promotion behavior in diff

[kgryte]

This PR:

• closes: docs: diff does not specify type promotion behavior #852
• clarifies that, when either prepend and append are of a different dtype than x, behavior is left unspecified, thus allowing array libraries to opt for either type promotion, casting, or raising an exception.
• maintains the status quo that the only portable behavior is when append and prepend have the same data type as x.

Notes

NumPy supports type promotion:

In [14]: x = np.ones(10,dtype="float32")

In [15]: x.dtype
Out[15]: dtype('float32')

In [16]: np.diff(x).dtype
Out[16]: dtype('float32')

In [17]: np.diff(x,prepend=np.ones(10))
Out[17]:
array([0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.,
       0., 0.])

In [18]: np.diff(x,prepend=np.ones(10)).dtype
Out[18]: dtype('float64')

However, the NumPy docs state:

The type of the output is the same as the type of the difference between any two elements of a. This is the same as the type of a in most cases. A notable exception is datetime64, which results in a timedelta64 output array.

We have yet, TMK, allowed optional array kwargs to affect the output array dtype. It is not obvious to me that we should establish such a precedent here.

[rgommers]

clarifies that, when either prepend and append are of a different dtype than x, behavior is left unspecified, thus allowing array libraries to opt for either type promotion, casting, or raising an exception.

That seems like the right decision to me, and aligns with what was discussed in the community meeting yesterday. It's also the most flexible decision - in case a real-world use case for something more prescriptive regarding type promotion arises in the future, we can deal with it then.

[kgryte]

As this change is a relatively minor documentation change, was discussed and agreed upon during a prior workgroup meeting, and has not received any objections, I'll go ahead and merge.