Simplify broadcastable a bit further and add docs

[mbauman]

Amazing what a great exercise writing documentation is. This is a followup to #26435, and more clearly lays out the requirements for defining a custom (non-AbstractArray) type that can participate in broadcasting. The biggest functional change here is that types that define their own BroadcastStyle must now also implement broadcastable to be a no-op.

[fredrikekre]

CI failure is

LoadError("sysimg.jl", 273, LoadError("broadcast.jl", 11, LoadError("broadcast.jl", 11, UndefVarError(Symbol("@__dot__")))))

[fredrikekre]

One too many )s

[fredrikekre]

[`axes`](@ref) or just `axes`

[fredrikekre]

desination -> destination

[mbauman]

Thanks! (On all counts)

[stevengj]

It seems like the BroadcastStyle(x) should be based on the value x, not on a type BroadcastStyle(T). (Imagine something like PyObject where the behavior might depend on the runtime value.) Is there a technical reason why it must take a type argument?

The biggest functional change here is that types that define their own BroadcastStyle must now also implement broadcastable to be a no-op.

What is wrong with something like

broadcastable(x) = _broadcastable(x, BroadcastStyle(typeof(x))
_broadcastable(x, ::Unknown) = ...deprecation...
_broadcastable(x, s) = x

so that no-op is the default for types that define their own BroadcastStyle?

[mbauman]

This started as a documentation issue and morphed into the code changes that were required to make the documentation simple and understandable.

Yes, I agree the need for the type to support ndims is rather limiting. I'd like to address that in the future — it'd be nice to just use length(axes(arg)). Note, though, that it is required to be type-stable for a type-stable broadcast.

As far as your other suggestion, the issue with doing it that way is that then every type that wants to participate in broadcasting must both define broadcastable (to avoid the collect fallback) and define their preferred BroadcastStyle (to avoid being classified as Unknown). How I was using Unknown before was kind-of an abuse — there isn't a base implementation for broadcasting Unknown styles. Indeed, the barebones Foo26601 would fail in surprising ways with that implementation. It's far more truthful to state that all types that quack like an array are DefaultArrayStyle. We just don't know if they'll quack like an array until after they become broadcastable.

IMO: broadcastable is the "simpler" API. It's the gateway into overriding behaviors. BroadcastStyle is far more complicated. It makes more sense to make the more complicated API require coordination with the simpler one than the other way around.

[stevengj]

Note, though, that it is required to be type-stable for a type-stable broadcast.

Broadcasting a PyObject will basically never be type-stable, and that's okay.

In the type-stable case, you don't lose anything by making BroadcastStyle(x) take the object x rather than the type T, so you only gain flexibility this way.

[mbauman]

It's a fairly disruptive change since everyone currently defines their BroadcastStyle methods on the type. Note that we could get around this with a definition like:

BroadcastStyle(x::T) where {T} = DefaultArrayStyle{applicable(ndims, T) ? ndims(T) : Any}()

But that requires an optimized and inferred applicable. That's why I'd like to tackle it on its own.

[stevengj]

It’s disruptive for people using an unreleased 0.7 feature... isn’t this precisely the time to fix the API?

[stevengj]

Besides, it could be backwards compatible if the instance-based constructor were defined as lowercase broadcaststyle(x). This would be more consistent with most of our traits functions anyway.

[mbauman]

Yeah, we're in agreement here. Are you saying you want me to do that in this PR? I'd still prefer to do it separately.

[stevengj]

Separately is fine with me.

[mbauman]

Closing and re-opening to re-run CI — I'll plan to merge this tomorrow and then followup with the proposed changes to BroadcastStyle.