RFC: clarify `broadcast_to` semantics

[adityagoel4512]

I'm finding the broadcast_to specification a little underspecified. In the docs we see the following for the shape parameter:

shape (Tuple[int, ...]) – array shape. Must be compatible with x (see Broadcasting). If the array is incompatible with the specified shape, the function should raise an exception.

The broadcasting link goes on to specify bidirectional broadcasting. That would imply to me that np.broadcast_to(np.asarray([[-1, -1], [-1, -1]]), (2, 1, 2)) should work since shapes (2, 2) and (2, 1, 2) are bidirectionally compatible. Somewhat reasonably in my opinion, NumPy did not interpret this in that way and raises an exception.

Since np.broadcast_to(np.asarray([[-1, -1], [-1, -1]]), (1, 2, 2)) does work, it seems that broadcasting compatibility is unidirectional. i.e. x.shape must be broadcastable to shape. Is it worth spelling out explicitly the difference in how this works, like ONNX does? I couldn't find any explanation in the standard itself.

It does say the following, although I read the "a specified shape" part as "any shape" rather than simply the shape parameter.

Returns: out (array) – an array having a specified shape. Must have the same data type as x.

If this ambiguity is shared I am happy to contribute a clarification.