docs for Base.promote_op

[simonbyrne]

Base.promote_op is used quite a bit through Base, mostly it seems for determining array output types, but it is undocumented. It would be nice to know (a) what it is supposed to do, and (b) where and when it can be used.

see also #25515 and #25591.

[martinholters]

(a) promote_op(f, argtypes...) guesses what an appropriate container eltype would be for storing results of f(::argtypes...). It invokes inference for coming up with the guess, so it can change its mind any time.
(b) It can safely be used whenever you don't care about the result (remember, it's just guessing). If you now think "but then I can never use it!", you got it. The only excuse to use it is if you don't have any elements to figure out their types and guessing is the best you can do. (E.g. broadcasting over empty input containers.)

Should I add that as a docstring to promote_op?

[martinholters]

Oh, an extra warning I forgot: its guess will very often at least be a supertype of what f(::argtypes...) could return, so one might be lured into believing this is always the case, but it's not. So it cannot be used to determined the eltype of a container that is guaranteed to be able to store the results (yes, preallocation of an output array based on promote_op may lead to failure).

[simonbyrne]

Yes, please open a PR.

[simonbyrne]

Well, it is used for determining non-empty container types, e.g. for matrix multiplication.

[martinholters]

Ref. #19669.