Improvement of documentation of [A, B, C, ...] syntax

[bkamins]

Julia Language Documentation in section 19.1.2 Construction and Initialization states:

The syntax [A, B, C, ...] constructs a 1-d array (vector) of its arguments.

However, the actual behavior is that it can construct a vector where its arguments get converted to a common promotion type if it exists. For example after:

a = [true, false]
b = [1,2]
c = [a, b]

we have that c[1] is:

2-element Array{Int64,1}:
 1
 0

and c1[1] === a is false but c[2] === b is true.

Therefore I would suggest to update the documentation in the following way:

The syntax [A, B, C, ...] constructs a 1-d array (vector) of its arguments. If all arguments have a common promotion type then they get converted to that type. In such a situation mutable arguments are stored in the new array by reference only if they do not have to be converted.

[TotalVerb]

I didn't even know that mutable types behaved this way.

julia> a = [1, 2, 3]
3-element Array{Int64,1}:
 1
 2
 3

julia> b = [1.0, 2.0, 3.0]
3-element Array{Float64,1}:
 1.0
 2.0
 3.0

julia> [a, b]
2-element Array{Array{Float64,1},1}:
 [1.0,2.0,3.0]
 [1.0,2.0,3.0]

julia> [a, b][1] === a
false

julia> [a, b][2] === b
true

It is not intuitive. 👍 to the documentation.

[tkelman]

this is effectively just #12441 in action