From be77f650deb8dbf6496e4bb85e19409a0459f1a5 Mon Sep 17 00:00:00 2001
From: Jeff Bezanson <jeff.bezanson@gmail.com>
Date: Thu, 8 Aug 2024 14:59:53 -0400
Subject: [PATCH] improve docs for `collect` and square brackets (#55352)

fixes #55350

---------

Co-authored-by: Neven Sajko <s@purelymail.com>
---
 base/abstractarray.jl |  2 ++
 base/array.jl         | 20 +++++++++++++++++++-
 base/broadcast.jl     |  1 +
 base/docs/basedocs.jl |  7 +++++--
 4 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/base/abstractarray.jl b/base/abstractarray.jl
index 40e36ce15f6ed..77aae63399ec8 100644
--- a/base/abstractarray.jl
+++ b/base/abstractarray.jl
@@ -3408,6 +3408,8 @@ mapany(f, itr) = Any[f(x) for x in itr]
 Transform collection `c` by applying `f` to each element. For multiple collection arguments,
 apply `f` elementwise, and stop when any of them is exhausted.
 
+The element type of the result is determined in the same manner as in [`collect`](@ref).
+
 See also [`map!`](@ref), [`foreach`](@ref), [`mapreduce`](@ref), [`mapslices`](@ref), [`zip`](@ref), [`Iterators.map`](@ref).
 
 # Examples
diff --git a/base/array.jl b/base/array.jl
index 008a52abb952e..648fedd5036e1 100644
--- a/base/array.jl
+++ b/base/array.jl
@@ -660,7 +660,7 @@ _array_for(::Type{T}, itr, isz) where {T} = _array_for(T, isz, _similar_shape(it
 
 
 """
-    collect(collection)
+    collect(iterator)
 
 Return an `Array` of all items in a collection or iterator. For dictionaries, returns
 a `Vector` of `key=>value` [Pair](@ref Pair)s. If the argument is array-like or is an iterator
@@ -671,6 +671,9 @@ Used by [comprehensions](@ref man-comprehensions) to turn a [generator expressio
 into an `Array`. Thus, *on generators*, the square-brackets notation may be used instead of calling `collect`,
 see second example.
 
+The element type of the returned array is based on the types of the values collected. However, if the
+iterator is empty then the element type of the returned (empty) array is determined by type inference.
+
 # Examples
 
 Collect items from a `UnitRange{Int64}` collection:
@@ -692,6 +695,21 @@ julia> collect(x^2 for x in 1:3)
  4
  9
 ```
+
+Collecting an empty iterator where the result type depends on type inference:
+
+```jldoctest
+julia> [rand(Bool) ? 1 : missing for _ in []]
+Union{Missing, Int64}[]
+```
+
+When the iterator is non-empty, the result type depends only on values:
+
+```julia-repl
+julia> [rand(Bool) ? 1 : missing for _ in [""]]
+1-element Vector{Int64}:
+ 1
+```
 """
 collect(itr) = _collect(1:1 #= Array =#, itr, IteratorEltype(itr), IteratorSize(itr))
 
diff --git a/base/broadcast.jl b/base/broadcast.jl
index 57eac7f3a094c..927c946e53e02 100644
--- a/base/broadcast.jl
+++ b/base/broadcast.jl
@@ -751,6 +751,7 @@ The resulting container type is established by the following rules:
  - All other combinations of arguments default to returning an `Array`, but
    custom container types can define their own implementation and promotion-like
    rules to customize the result when they appear as arguments.
+ - The element type is determined in the same manner as in [`collect`](@ref).
 
 A special syntax exists for broadcasting: `f.(args...)` is equivalent to
 `broadcast(f, args...)`, and nested `f.(g.(args...))` calls are fused into a
diff --git a/base/docs/basedocs.jl b/base/docs/basedocs.jl
index 2ed1bd98caa5c..e03d0db78f29f 100644
--- a/base/docs/basedocs.jl
+++ b/base/docs/basedocs.jl
@@ -663,8 +663,11 @@ kw"{", kw"{}", kw"}"
 """
     []
 
-Square braces are used for [indexing](@ref man-array-indexing), [indexed assignment](@ref man-indexed-assignment),
-[array literals](@ref man-array-literals), and [array comprehensions](@ref man-comprehensions).
+Square brackets are used for [indexing](@ref man-array-indexing) ([`getindex`](@ref)),
+[indexed assignment](@ref man-indexed-assignment) ([`setindex!`](@ref)),
+[array literals](@ref man-array-literals) ([`Base.vect`](@ref)),
+[array concatenation](@ref man-array-concatenation) ([`vcat`](@ref), [`hcat`](@ref), [`hvcat`](@ref), [`hvncat`](@ref)),
+and [array comprehensions](@ref man-comprehensions) ([`collect`](@ref)).
 """
 kw"[", kw"[]", kw"]"