Reword doc on undef arrays with missing

[knuesel]

This is a follow-up to #31091. The intent is to make clear that undef constructors are not the right way to initialize arrays to missing. This way, other array implementations (such as SentinelArrays.jl) are free to provide faster undef constructors that actually leave data uninitialized (without creating an incompatiblity with specified behavior from Base).

[bkamins]

maybe better say that this is the current behavior, but in general it should be treated as undefined for the purposes of the contract that the docstring gives. I thought this was your intention (with which I agree).

@nalimilan is probably better than me with suggesting a proper wording 😄.

[quinnj]

Yeah, definitely better to emphasize the "undefined"-ness, hence undef, and that whatever is initialized shouldn't be relied on.

[knuesel]

Yes that was my intention 😊

I wanted to avoid "currently" because it implies that the behavior might change, but it's precisely the part mentioned here that won't change according to Jeff. I didn't want the documentation to include something misleading... On the other hand, a permanent truth is currently true so "currently" is technically correct.

I also thought it was useful to mention "due to implementation details", otherwise the reader would think "then why the heck do they initialize these values!".

Here are two proposals:

    Due to implementation details, uninitialized arrays created with
    `Array{Union{Missing, T}}(undef, dims)` or with `similar` are actually
    filled with `missing` values in most cases where `T` is a bits type
    (`isbitstype(T)` returns `true`). However, this behavior is specific to
    `Base.Array` and is not reliable (it can fail when `T` is a singleton type).
    Values returned by `undef` constructors should be treated as undefined. Use
    a `missing` constructor as shown above to initialize values to `missing`.

and

    In the current implementation, uninitialized `Base` arrays as created with
    `Array{Union{Missing, T}}(undef, dims)` or with `similar` are actually
    filled with `missing` values in most cases where `T` is a bits type
    (`isbitstype(T)` returns `true`). This behavior should not be relied upon:
    values returned by `undef` constructors should be treated as undefined. Use
    a `missing` constructor as shown above to initialize values to `missing`.

I slightly prefer the second one. What do you think?

[bkamins]

probably core devs should pick here 😄

[knuesel]

OK let's wait for their input then!

[JeffBezanson]

It should just say something like "using undef may currently give an array filled with missing, but this is not the correct way to obtain such an array. pass missing to the constructor instead." There's no need to mention bits types etc., it just confuses the issue.

[knuesel]

@JeffBezanson thanks for the feedback, I have updated the PR with a wording close to this.