Clarify the difference between collect and bracket notation for generators (#50619)

As a follow-up to my question on the forum [Unclear documentation of
`collect`? (similarity and difference with
brackets)](https://discourse.julialang.org/t/unclear-documentation-of-collect-similarity-and-difference-with-brackets/),
here is a tentative expansion of the docstring of `Base.collect` to
clarify both the similarities and differences with the bracket notation
for generators.

I'm pretty sure it needs so edits, but here are the motivating factors
behind the changes, by decreasing order of importance:
1. avoid the presence of bracket notation in the example without
explanation (in the present docstring, I find it highly *implicit*)
2. simplification of examples to focus on the topic (and not on range
syntax or filtering in comprehensions)
3. avoid wasting vertical space by using longer than needed
iterators/generators

Feedback on my formulation is welcome!

---------

Co-authored-by: Max Horn <[email protected]>
Co-authored-by: Jishnu Bhattacharya <[email protected]>

Author: 3 people

base/array.jl

@@ -672,30 +672,34 @@ _array_for(::Type{T}, itr, isz) where {T} = _array_for(T, isz, _similar_shape(it
     collect(collection)
 
 Return an `Array` of all items in a collection or iterator. For dictionaries, returns
-`Vector{Pair{KeyType, ValType}}`. If the argument is array-like or is an iterator with the
-[`HasShape`](@ref IteratorSize) trait, the result will have the same shape
+a `Vector` of `key=>value` [Pair](@ref Pair)s. If the argument is array-like or is an iterator
+with the [`HasShape`](@ref IteratorSize) trait, the result will have the same shape
 and number of dimensions as the argument.
 
-Used by comprehensions to turn a generator into an `Array`.
+Used by [comprehensions](@ref man-comprehensions) to turn a [generator expression](@ref man-generators)
+into an `Array`. Thus, *on generators*, the square-brackets notation may be used instead of calling `collect`,
+see second example.
 
 # Examples
+
+Collect items from a `UnitRange{Int64}` collection:
+
 ```jldoctest
-julia> collect(1:2:13)
-7-element Vector{Int64}:
-  1
-  3
-  5
-  7
-  9
- 11
- 13
+julia> collect(1:3)
+3-element Vector{Int64}:
+ 1
+ 2
+ 3
+```
 
-julia> [x^2 for x in 1:8 if isodd(x)]
-4-element Vector{Int64}:
-  1
-  9
- 25
- 49
+Collect items from a generator (same output as `[x^2 for x in 1:3]`):
+
+```jldoctest
+julia> collect(x^2 for x in 1:3)
+3-element Vector{Int64}:
+ 1
+ 4
+ 9
 ```
 """
 collect(itr) = _collect(1:1 #= Array =#, itr, IteratorEltype(itr), IteratorSize(itr))

doc/src/manual/arrays.md

@@ -398,7 +398,7 @@ the result in single precision by writing:
 Float32[ 0.25*x[i-1] + 0.5*x[i] + 0.25*x[i+1] for i=2:length(x)-1 ]
 ```
 
-## Generator Expressions
+## [Generator Expressions](@id man-generators)
 
 Comprehensions can also be written without the enclosing square brackets, producing an object
 known as a generator. This object can be iterated to produce values on demand, instead of allocating