Improve docs on Broadcasting

[oxinabox]

Reposting this from for https://github.com/malmaud/TensorFlow.jl/issues/429#issuecomment-419730407 for @adamryczkowski

I would really like to help you, but I do not feel the developing of broadcast mechanism well enough, to implement it here. I claim that the few pages dedicated to the broadcast in the Julia's current manual (Customizing broadcasting) are some of the least clear.

The manual does not explain what role exactly objects of type BroadcastStyle play. Names suggest they have something to do with the building of the iteration loop - I guess iterating over linear indices or using multidimensional array indexing - but that is only my guess, and I do not have a faint idea how to customize it (to e.g. to use row-major indexing for some custom types).

I also do not understand, why function with the name similar is used for allocation of the output container. Or maybe it is just a poor choice of a function name, and in this case, I would really like to know the history of choosing such a name.

I also try to implement my own toy type to define custom broadcasting for them, but this effort is also hindered by poor (in my opinion) documentation; to really do a meaningful example of broadcasting, I feel that I need to define a type with my own range iterators. But alas, the interfaces (informal, of course) for all those abstract ancestors of UnitRange are undocumented...

I think it is correct. It matches my experience The docs for broadcasting could use some work. I do appreciate that is is a complicated idea (particularly with all it's flexibility) and hard to explain well.

So opening this issue to track that it could do with a few more read overs. This is a follow up to https://github.com/JuliaLang/julia/issues/20740 and probably others.

I wonder if some parts of @mbauman's JuliaCon talk could be extracted, to give a higher level introduction to that section. And maybe even that talk could be linked in the docs, as an external resource?

[mbauman]

This is helpful — thanks. I'll try to take a stab at improving this.

[adamryczkowski]

@mbauman Another portion of (confused and incomplete) material can be found here: https://discourse.julialang.org/t/how-to-customize-the-new-broadcasting-infrastructure-in-v0-7/11322 .

I am willing to participate in the creation of the manual, provided I first understand it myself. So, if you prefer, you can schedule a meeting with me, answer about 10-20 questions I have about the broadcasting, and I will contribute to the manual myself.

[mbauman]

That'd be great. I'd be very happy to on-board you here — I've often found it's better to have someone different write the docs. You can contact me directly via email or on Slack and we can arrange for a one-on-one.