add public statement to Base.Broadcast

[matthias314]

This PR makes the following symbols from Base.Broadcast public:

• Symbols appearing in the documentation, with docstring

AbstractArrayStyle
ArrayStyle
Broadcasted
DefaultArrayStyle
Style
combine_axes
combine_styles
flatten
instantiate
result_style

• Symbols appearing in the documentation, without docstring

Unknown

• Symbols not appearing in the documentation, with docstring

materialize

I think it makes sense to make it public given that Broadcasted is also public.

• Symbols not appearing in the documentation, without docstring

DefaultMatrixStyle
DefaultVectorStyle

I think it makes sense to have them available as shortcuts. Maybe one should even mention them in the documentation instead of using DefaultArrayStyle{1}, for example.

EDIT: Making DefaultVectorStyle and DefaultMatrixStyle public leads to failing doctests because they now appear in the Julia output instead of DefaultArrayStyle{1} and DefaultArrayStyle{2}. However, they are never used in broadcast.jl. If one doesn't want to have them public, why are they defined at all? Let me know if you want to have them public. Then I adjust the documentation.

• The following functions have been left out although they have docstrings:

broadcast_preserving_zero_d
broadcast_shape
make_makeargs
newindex
_broadcast_getindex

• The following symbol (with docstring) is currently exported without appearing in the documentation:

BroadcastFunction

[matthias314]

I've removed DefaultVectorStyle and DefaultMatrixStyle from the list of public symbols.

[matthias314]

@LilithHafner Any feedback on this?

[LilithHafner]

Thanks for the bump.

• I don't think we should mark anything without a docstring as public without also adding a docstring.
• I don't know the broadcast internals well enough to provide robust feedback on the specific choices here but I'll try to find someone(s) who is.

[matthias314]

Any news?

I can add a docstring for Broadcast.Unknown if you want. The only occurrence of Unknown is in some output inside the examples section of the docstring for Broadcast.result_style. If we work on this, should we also consider renaming it? I think that UnknownStyle would be more informative.

[Tokazama]

I was pretty surprised to find out these didn't make the first round of public declarations. Is there any reason this hasn't been pushed forward?

[matthias314]

I was waiting for feedback about how to proceed with Broadcast.Unknown. Should it be public? If yes, should it be renamed to UnknownStyle?

[Tokazama]

I think namespacing it makes it less of a problem to rename it as UnkownStyle. It's always nice to have a consistent syntax. TBH, rules related to naming styles and enums in Julia are lost on me.

[matthias314]

What does this mean in terms of answers to my two questions?

[Tokazama]

Sorry, I saw the triage label and justj added a quick opinion instead of answering any solid questions.

1. It should be public since it's a pretty important part of the other methods being made public here.
2. Renaming it isn't necessary to avoid conflicts or confusion because there isn't going to be another Broadcast.Unknown, leaving info a simple doc string away from understanding. However, it's always nice to conform to a syntactic standard.

That being said, triage may have a different response.

[LilithHafner]

We should add docstrings instead of adding exceptions to this test.

[LilithHafner]

Triage thinks that this is generally fine but defers to @mbauman to make sure that these are actually the public API of broadcasting.

[LilithHafner]

Should Base.broadcasted be public, too?

[Tokazama]

Should Base.broadcasted be public, too?

I'm in favor of making it public if we can agree on an interface, because I recall having to override it sometimes. For example, documenting that new method definitions should dispatch on specifically on the Base.broadcasted(::MyStyle, f, args...) to avoid ambiguities.