From 71396b21ddaa7358feea79f1b675c755f5874ccd Mon Sep 17 00:00:00 2001
From: Michael Abbott <32575566+mcabbott@users.noreply.github.com>
Date: Sun, 21 Aug 2022 03:07:18 -0400
Subject: [PATCH 1/6] improve docs for cat, hcat, vcat

---
 base/abstractarray.jl | 192 +++++++++++++++++++++++-------------------
 1 file changed, 105 insertions(+), 87 deletions(-)

diff --git a/base/abstractarray.jl b/base/abstractarray.jl
index 5db773b7d8ae7..e65042b112dd7 100644
--- a/base/abstractarray.jl
+++ b/base/abstractarray.jl
@@ -1813,41 +1813,55 @@ end
 """
     vcat(A...)
 
-Concatenate along dimension 1. To efficiently concatenate a large vector of arrays,
-use `reduce(vcat, x)`.
+Concatenate arrays or numbers vertically. Equivalent to [`cat`](@ref)`(A...; dims=1)`,
+which is also called by the syntax `[a; b; c]`.
+
+To concatenate a large vector of arrays, `reduce(vcat, A)` calls an efficient method
+when `A isa AbstractVector{<:AbstractVecOrMat}`, rather than working pairwise.
+
+See also [`hcat`](@ref), [`Iterators.flatten`](@ref), [`stack`](@ref).
 
 # Examples
 ```jldoctest
-julia> a = [1 2 3 4 5]
-1×5 Matrix{Int64}:
- 1  2  3  4  5
+julia> v = vcat([1,2], [3,4])
+4-element Vector{Int64}:
+ 1
+ 2
+ 3
+ 4
 
-julia> b = [6 7 8 9 10; 11 12 13 14 15]
-2×5 Matrix{Int64}:
-  6   7   8   9  10
- 11  12  13  14  15
+julia> v == vcat(1, 2, [3,4])  # accepts numbers
+true
 
-julia> vcat(a,b)
-3×5 Matrix{Int64}:
-  1   2   3   4   5
-  6   7   8   9  10
- 11  12  13  14  15
+julia> v == [1; 2; [3,4]]  # syntax for the same operation
+true
 
-julia> c = ([1 2 3], [4 5 6])
-([1 2 3], [4 5 6])
+julia> summary(ComplexF64[1; 2; [3,4]])  # syntax for supplying the element type
+"4-element Vector{ComplexF64}"
 
-julia> vcat(c...)
-2×3 Matrix{Int64}:
- 1  2  3
- 4  5  6
+julia> vcat(range(1, 2, length=3))  # collects lazy ranges
+3-element Vector{Float64}:
+ 1.0
+ 1.5
+ 2.0
+
+julia> vcat(3, [], [4.5;;])  # empty vector Any[] affects the eltype 
+2×1 Matrix{Any}:
+ 3
+ 4.5
+
+julia> two = ([10, 20, 30]', Float64[4 5 6; 7 8 9])  # row vector and a matrix
+([10 20 30], [4.0 5.0 6.0; 7.0 8.0 9.0])
+
+julia> vcat(two...)
+3×3 Matrix{Float64}:
+ 10.0  20.0  30.0
+  4.0   5.0   6.0
+  7.0   8.0   9.0
 
-julia> vs = [[1, 2], [3, 4], [5, 6]]
-3-element Vector{Vector{Int64}}:
- [1, 2]
- [3, 4]
- [5, 6]
+julia> vs = [[1, 2], [3, 4], [5, 6]];
 
-julia> reduce(vcat, vs)
+julia> reduce(vcat, vs)  # more efficient than vcat(vs...)
 6-element Vector{Int64}:
  1
  2
@@ -1855,69 +1869,62 @@ julia> reduce(vcat, vs)
  4
  5
  6
+ 
+julia> ans == collect(Iterators.flatten(vs))
+true 
 ```
 """
 vcat(X...) = cat(X...; dims=Val(1))
 """
     hcat(A...)
 
-Concatenate along dimension 2. To efficiently concatenate a large vector of arrays,
-use `reduce(hcat, x)`.
+Concatenate arrays or numbers horizontally. Equivalent to [`cat`](@ref)`(A...; dims=2)`,
+which is also called by the syntax `[a b c]` or `[a;;]`.
+
+For a large vector of arrays, `reduce(hcat, A)` calls an efficient method
+when `A isa AbstractVector{<:AbstractVecOrMat}`.
+For a vector of vectors, this can also be written [`stack`](@ref)`(A)`.
+
+See also [`vcat`](@ref), [`hvcat`](@ref).
 
 # Examples
 ```jldoctest
-julia> a = [1; 2; 3; 4; 5]
-5-element Vector{Int64}:
- 1
- 2
- 3
- 4
- 5
+julia> hcat([1,2], [3,4], [5,6])
+2×3 Matrix{Int64}:
+ 1  3  5
+ 2  4  6
 
-julia> b = [6 7; 8 9; 10 11; 12 13; 14 15]
-5×2 Matrix{Int64}:
-  6   7
-  8   9
- 10  11
- 12  13
- 14  15
-
-julia> hcat(a,b)
-5×3 Matrix{Int64}:
- 1   6   7
- 2   8   9
- 3  10  11
- 4  12  13
- 5  14  15
-
-julia> c = ([1; 2; 3], [4; 5; 6])
-([1, 2, 3], [4, 5, 6])
-
-julia> hcat(c...)
-3×2 Matrix{Int64}:
- 1  4
- 2  5
- 3  6
+julia> hcat(1, 2, [30 40], [5, 6]')
+1×6 Matrix{Int64}:
+ 1  2  30  40  5  6
 
-julia> x = Matrix(undef, 3, 0)  # x = [] would have created an Array{Any, 1}, but need an Array{Any, 2}
-3×0 Matrix{Any}
+julia> ans == [1 2 [30 40] [5, 6]']  # syntax for the same operation
+true
 
-julia> hcat(x, [1; 2; 3])
-3×1 Matrix{Any}:
- 1
- 2
- 3
+julia> Float32[1 2 [30 40] [5, 6]']  # syntax for supplying the eltype
+1×6 Matrix{Float32}:
+ 1.0  2.0  30.0  40.0  5.0  6.0
 
-julia> vs = [[1, 2], [3, 4], [5, 6]]
-3-element Vector{Vector{Int64}}:
- [1, 2]
- [3, 4]
- [5, 6]
+julia> ms = [zeros(2,2), [1 2; 3 4], [50 60; 70 80]];
 
-julia> reduce(hcat, vs)
-2×3 Matrix{Int64}:
- 1  3  5
- 2  4  6
+julia> reduce(hcat, ms)  # more efficient than hcat(ms...)
+2×6 Matrix{Float64}:
+ 0.0  0.0  1.0  2.0  50.0  60.0
+ 0.0  0.0  3.0  4.0  70.0  80.0
+
+julia> stack(ms) |> summary  # disagrees on a vector of matrices
+"2×2×3 Array{Float64, 3}"
+
+julia> hcat(Int[], Int[], Int[])  # empty vectors, each of size (0,)
+0×3 Matrix{Int64}
+
+julia> col0 = Matrix(undef, 2, 0)  # empty matrix, size (2,0)
+2×0 Matrix{Any}
+
+julia> hcat([1.1, 9.9], col0, ms[3])
+2×3 Matrix{Any}:
+ 1.1  50  60
+ 9.9  70  80
 ```
 """
 hcat(X...) = cat(X...; dims=Val(2))
@@ -1928,19 +1935,23 @@ typed_hcat(::Type{T}, X...) where T = _cat_t(Val(2), T, X...)
 """
     cat(A...; dims)
 
-Concatenate the input arrays along the specified dimensions in the iterable `dims`. For
-dimensions not in `dims`, all input arrays should have the same size, which will also be the
-size of the output array along that dimension. For dimensions in `dims`, the size of the
-output array is the sum of the sizes of the input arrays along that dimension. If `dims` is
-a single number, the different arrays are tightly stacked along that dimension. If `dims` is
-an iterable containing several dimensions, this allows one to construct block diagonal
-matrices and their higher-dimensional analogues by simultaneously increasing several
-dimensions for every new input array and putting zero blocks elsewhere. For example,
-`cat(matrices...; dims=(1,2))` builds a block diagonal matrix, i.e. a block matrix with
-`matrices[1]`, `matrices[2]`, ... as diagonal blocks and matching zero blocks away from the
-diagonal.
+Concatenate the input arrays along the dimensions specified in `dims`.
+
+Along a dimension `d in dims`, the size of the output array is `sum(size(a,d) for
+a in A)`. 
+Along other dimensions, all input arrays should have the same size,
+which will also be the size of the output array along those dimensions.
+
+If `dims` is a single number, the different arrays are tightly packed along that dimension. 
+If `dims` is an iterable containing several dimensions, the positions along these dimensions
+are increased simultaneously for each input array, filling with zero elsewhere.
+This allows one to construct block-diagonal matrices as `cat(matrices...; dims=(1,2))`, 
+and their higher-dimensional analogues.
 
-See also [`hcat`](@ref), [`vcat`](@ref), [`hvcat`](@ref), [`repeat`](@ref).
+The keyword also accepts `Val(dims)`.
+
+The special case `dims=1` is [`vcat`](@ref), and `dims=2` is [`hcat`](@ref).
+See also [`hvcat`](@ref), [`stack`](@ref), [`repeat`](@ref).
 
 # Examples
 ```jldoctest
@@ -1950,12 +1961,19 @@ julia> cat([1 2; 3 4], [pi, pi], fill(10, 2,3,1); dims=2)
  1.0  2.0  3.14159  10.0  10.0  10.0
  3.0  4.0  3.14159  10.0  10.0  10.0
 
+julia> size([pi, pi], 3)
+1
+
 julia> cat(true, trues(2,2), trues(4)', dims=(1,2))
 4×7 Matrix{Bool}:
  1  0  0  0  0  0  0
  0  1  1  0  0  0  0
  0  1  1  0  0  0  0
  0  0  0  1  1  1  1
+
+julia> cat(1, [2], [3;;]; dims=Val(2))
+1×3 Matrix{Int64}:
+ 1  2  3
 ```
 """
 @inline cat(A...; dims) = _cat(dims, A...)

From 6d8928a21ebc0808955d47b97344561b708a3e06 Mon Sep 17 00:00:00 2001
From: Michael Abbott <32575566+mcabbott@users.noreply.github.com>
Date: Sun, 21 Aug 2022 03:07:31 -0400
Subject: [PATCH 2/6] add cross-references

---
 base/abstractarray.jl | 9 +++++++--
 base/reducedim.jl     | 3 +++
 base/slicearray.jl    | 6 ++++++
 3 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/base/abstractarray.jl b/base/abstractarray.jl
index e65042b112dd7..ab21355574820 100644
--- a/base/abstractarray.jl
+++ b/base/abstractarray.jl
@@ -3082,7 +3082,7 @@ concatenated along the remaining dimensions.
 For example, if `dims = [1,2]` and `A` is 4-dimensional, then `f` is called on `x = A[:,:,i,j]`
 for all `i` and `j`, and `f(x)` becomes `R[:,:,i,j]` in the result `R`.
 
-See also [`eachcol`](@ref), [`eachslice`](@ref), [`mapreduce`](@ref).
+See also [`eachcol`](@ref) or [`eachslice`](@ref), used with [`map`](@ref) or [`stack`](@ref).
 
 # Examples
 ```jldoctest
@@ -3102,7 +3102,7 @@ julia> A = reshape(1:30,(2,5,3))
 
 julia> f(x::Matrix) = fill(x[1,1], 1,4);  # returns a 1×4 matrix
 
-julia> mapslices(f, A, dims=(1,2))
+julia> B = mapslices(f, A, dims=(1,2))
 1×4×3 Array{$Int, 3}:
 [:, :, 1] =
  1  1  1  1
@@ -3113,6 +3113,11 @@ julia> mapslices(f, A, dims=(1,2))
 [:, :, 3] =
  21  21  21  21
 
+julia> f(x::AbstractMatrix) = fill(x[1,1], 1,4);
+
+julia> B == stack(f, eachslice(A, dims=3))
+true
+
 julia> g(x) = x[begin] // x[end-1];  # returns a number
 
 julia> mapslices(g, A, dims=[1,3])
diff --git a/base/reducedim.jl b/base/reducedim.jl
index dc34b4feb1f6a..d3d6e68b404ef 100644
--- a/base/reducedim.jl
+++ b/base/reducedim.jl
@@ -382,6 +382,9 @@ The associativity of the reduction is implementation-dependent; if you need a pa
 associativity, e.g. left-to-right, you should write your own loop or consider using
 [`foldl`](@ref) or [`foldr`](@ref). See documentation for [`reduce`](@ref).
 
+There are special efficient methods for `reduce(`[`vcat`](@ref)`, xs)` and 
+`reduce(`[`hcat`](@ref)`, xs)` for certain arrays of arrays; see also [`stack`](@ref).
+
 # Examples
 ```jldoctest
 julia> a = reshape(Vector(1:16), (4,4))
diff --git a/base/slicearray.jl b/base/slicearray.jl
index 85fcb56e4278d..506cc900ba781 100644
--- a/base/slicearray.jl
+++ b/base/slicearray.jl
@@ -85,6 +85,8 @@ the ordering of the dimensions will match those in `dims`. If `drop = false`, th
 `Slices` will have the same dimensionality as the underlying array, with inner
 dimensions having size 1.
 
+See [`stack`](@ref)`(slices; dims)` for the inverse of `eachcol(A; dims::Integer, drop=true)`.
+
 See also [`eachrow`](@ref), [`eachcol`](@ref), [`mapslices`](@ref) and [`selectdim`](@ref).
 
 !!! compat "Julia 1.1"
@@ -131,6 +133,8 @@ end
 Create a [`RowSlices`](@ref) object that is a vector of rows of matrix or vector `A`.
 Row slices are returned as `AbstractVector` views of `A`.
 
+For the inverse, see [`stack`](@ref)`(rows; dims=1)`.
+
 See also [`eachcol`](@ref), [`eachslice`](@ref) and [`mapslices`](@ref).
 
 !!! compat "Julia 1.1"
@@ -167,6 +171,8 @@ eachrow(A::AbstractVector) = eachrow(reshape(A, size(A,1), 1))
 Create a [`ColumnSlices`](@ref) object that is a vector of columns of matrix or vector `A`.
 Column slices are returned as `AbstractVector` views of `A`.
 
+For the inverse, see [`stack`](@ref)`(cols)` or `reduce(`[`hcat`](@ref)`, cols)`.
+
 See also [`eachrow`](@ref), [`eachslice`](@ref) and [`mapslices`](@ref).
 
 !!! compat "Julia 1.1"

From 791c68be691788110d5714e0faccea0592f0ef8b Mon Sep 17 00:00:00 2001
From: Michael Abbott <32575566+mcabbott@users.noreply.github.com>
Date: Sun, 21 Aug 2022 13:26:01 -0400
Subject: [PATCH 3/6] spaces

---
 base/abstractarray.jl | 12 ++++++------
 base/reducedim.jl     |  2 +-
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/base/abstractarray.jl b/base/abstractarray.jl
index ab21355574820..d4773c43a5de3 100644
--- a/base/abstractarray.jl
+++ b/base/abstractarray.jl
@@ -1845,7 +1845,7 @@ julia> vcat(range(1, 2, length=3))  # collects lazy ranges
  1.5
  2.0
 
-julia> vcat(3, [], [4.5;;])  # empty vector Any[] affects the eltype 
+julia> vcat(3, [], [4.5;;])  # empty vector Any[] affects the eltype
 2×1 Matrix{Any}:
  3
  4.5
@@ -1869,9 +1869,9 @@ julia> reduce(vcat, vs)  # more efficient than vcat(vs...)
  4
  5
  6
- 
+
 julia> ans == collect(Iterators.flatten(vs))
-true 
+true
 ```
 """
 vcat(X...) = cat(X...; dims=Val(1))
@@ -1938,14 +1938,14 @@ typed_hcat(::Type{T}, X...) where T = _cat_t(Val(2), T, X...)
 Concatenate the input arrays along the dimensions specified in `dims`.
 
 Along a dimension `d in dims`, the size of the output array is `sum(size(a,d) for
-a in A)`. 
+a in A)`.
 Along other dimensions, all input arrays should have the same size,
 which will also be the size of the output array along those dimensions.
 
-If `dims` is a single number, the different arrays are tightly packed along that dimension. 
+If `dims` is a single number, the different arrays are tightly packed along that dimension.
 If `dims` is an iterable containing several dimensions, the positions along these dimensions
 are increased simultaneously for each input array, filling with zero elsewhere.
-This allows one to construct block-diagonal matrices as `cat(matrices...; dims=(1,2))`, 
+This allows one to construct block-diagonal matrices as `cat(matrices...; dims=(1,2))`,
 and their higher-dimensional analogues.
 
 The keyword also accepts `Val(dims)`.
diff --git a/base/reducedim.jl b/base/reducedim.jl
index d3d6e68b404ef..560b54511e79e 100644
--- a/base/reducedim.jl
+++ b/base/reducedim.jl
@@ -382,7 +382,7 @@ The associativity of the reduction is implementation-dependent; if you need a pa
 associativity, e.g. left-to-right, you should write your own loop or consider using
 [`foldl`](@ref) or [`foldr`](@ref). See documentation for [`reduce`](@ref).
 
-There are special efficient methods for `reduce(`[`vcat`](@ref)`, xs)` and 
+There are special efficient methods for `reduce(`[`vcat`](@ref)`, xs)` and
 `reduce(`[`hcat`](@ref)`, xs)` for certain arrays of arrays; see also [`stack`](@ref).
 
 # Examples

From ab4b6082c7122a72c3e2c07b4e717f9a873a9a8b Mon Sep 17 00:00:00 2001
From: Michael Abbott <32575566+mcabbott@users.noreply.github.com>
Date: Tue, 13 Sep 2022 01:03:35 -0400
Subject: [PATCH 4/6] tweaks in reply to own comments

---
 base/abstractarray.jl | 4 ++--
 base/reduce.jl        | 6 ++++--
 base/reducedim.jl     | 3 ---
 3 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/base/abstractarray.jl b/base/abstractarray.jl
index d4773c43a5de3..af02a9b22e02b 100644
--- a/base/abstractarray.jl
+++ b/base/abstractarray.jl
@@ -3113,9 +3113,9 @@ julia> B = mapslices(f, A, dims=(1,2))
 [:, :, 3] =
  21  21  21  21
 
-julia> f(x::AbstractMatrix) = fill(x[1,1], 1,4);
+julia> f2(x::AbstractMatrix) = fill(x[1,1], 1,4);
 
-julia> B == stack(f, eachslice(A, dims=3))
+julia> B == stack(f2, eachslice(A, dims=3))
 true
 
 julia> g(x) = x[begin] // x[end-1];  # returns a number
diff --git a/base/reduce.jl b/base/reduce.jl
index a7f821a73be92..c61f7f4ccf72a 100644
--- a/base/reduce.jl
+++ b/base/reduce.jl
@@ -459,8 +459,10 @@ For empty collections, providing `init` will be necessary, except for some speci
 neutral element of `op`.
 
 Reductions for certain commonly-used operators may have special implementations, and
-should be used instead: `maximum(itr)`, `minimum(itr)`, `sum(itr)`, `prod(itr)`,
- `any(itr)`, `all(itr)`.
+should be used instead: [`maximum`](@ref)`(itr)`, [`minimum`](@ref)`(itr)`, [`sum`](@ref)`(itr)`,
+[`prod`](@ref)`(itr)`, [`any`](@ref)`(itr)`, [`all`](@ref)`(itr)`.
+There are efficient methods for concatenating certain arrays of arrays
+by calling `reduce(`[`vcat`](@ref)`, arr)` or `reduce(`[`hcat`](@ref)`, arr)`.
 
 The associativity of the reduction is implementation dependent. This means that you can't
 use non-associative operations like `-` because it is undefined whether `reduce(-,[1,2,3])`
diff --git a/base/reducedim.jl b/base/reducedim.jl
index 560b54511e79e..dc34b4feb1f6a 100644
--- a/base/reducedim.jl
+++ b/base/reducedim.jl
@@ -382,9 +382,6 @@ The associativity of the reduction is implementation-dependent; if you need a pa
 associativity, e.g. left-to-right, you should write your own loop or consider using
 [`foldl`](@ref) or [`foldr`](@ref). See documentation for [`reduce`](@ref).
 
-There are special efficient methods for `reduce(`[`vcat`](@ref)`, xs)` and
-`reduce(`[`hcat`](@ref)`, xs)` for certain arrays of arrays; see also [`stack`](@ref).
-
 # Examples
 ```jldoctest
 julia> a = reshape(Vector(1:16), (4,4))

From 1640f29923d09471e084db6798fdf4ab9f531d6b Mon Sep 17 00:00:00 2001
From: Michael Abbott <32575566+mcabbott@users.noreply.github.com>
Date: Tue, 20 Sep 2022 21:28:22 -0400
Subject: [PATCH 5/6] fix last doctest

---
 base/abstractarray.jl | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/base/abstractarray.jl b/base/abstractarray.jl
index af02a9b22e02b..8e7169a4f47af 100644
--- a/base/abstractarray.jl
+++ b/base/abstractarray.jl
@@ -1923,8 +1923,8 @@ julia> col0 = Matrix(undef, 2, 0)  # empty matrix, size (2,0)
 
 julia> hcat([1.1, 9.9], col0, ms[3])
 2×3 Matrix{Any}:
- 1.1  50  60
- 9.9  70  80
+ 1.1  50.0  60.0
+ 9.9  70.0  80.0
 ```
 """
 hcat(X...) = cat(X...; dims=Val(2))

From 18000fe4c38995a729ca92555af76473e419ecaa Mon Sep 17 00:00:00 2001
From: Michael Abbott <32575566+mcabbott@users.noreply.github.com>
Date: Fri, 28 Oct 2022 17:52:19 -0400
Subject: [PATCH 6/6] tweaks & simplifications + compat note for
 dims=Val((1,2))

---
 base/abstractarray.jl | 48 ++++++++++++++++++-------------------------
 1 file changed, 20 insertions(+), 28 deletions(-)

diff --git a/base/abstractarray.jl b/base/abstractarray.jl
index 8e7169a4f47af..b0b9bf3ce5919 100644
--- a/base/abstractarray.jl
+++ b/base/abstractarray.jl
@@ -1814,7 +1814,7 @@ end
     vcat(A...)
 
 Concatenate arrays or numbers vertically. Equivalent to [`cat`](@ref)`(A...; dims=1)`,
-which is also called by the syntax `[a; b; c]`.
+and to the syntax `[a; b; c]`.
 
 To concatenate a large vector of arrays, `reduce(vcat, A)` calls an efficient method
 when `A isa AbstractVector{<:AbstractVecOrMat}`, rather than working pairwise.
@@ -1845,11 +1845,6 @@ julia> vcat(range(1, 2, length=3))  # collects lazy ranges
  1.5
  2.0
 
-julia> vcat(3, [], [4.5;;])  # empty vector Any[] affects the eltype
-2×1 Matrix{Any}:
- 3
- 4.5
-
 julia> two = ([10, 20, 30]', Float64[4 5 6; 7 8 9])  # row vector and a matrix
 ([10 20 30], [4.0 5.0 6.0; 7.0 8.0 9.0])
 
@@ -1879,7 +1874,7 @@ vcat(X...) = cat(X...; dims=Val(1))
     hcat(A...)
 
 Concatenate arrays or numbers horizontally. Equivalent to [`cat`](@ref)`(A...; dims=2)`,
-which is also called by the syntax `[a b c]` or `[a;;]`.
+and to the syntax `[a b c]` or `[a;; b;; c]`.
 
 For a large vector of arrays, `reduce(hcat, A)` calls an efficient method
 when `A isa AbstractVector{<:AbstractVecOrMat}`.
@@ -1894,16 +1889,16 @@ julia> hcat([1,2], [3,4], [5,6])
  1  3  5
  2  4  6
 
-julia> hcat(1, 2, [30 40], [5, 6]')
-1×6 Matrix{Int64}:
- 1  2  30  40  5  6
+julia> hcat(1, 2, [30 40], [5, 6, 7]')  # accepts numbers
+1×7 Matrix{Int64}:
+ 1  2  30  40  5  6  7
 
-julia> ans == [1 2 [30 40] [5, 6]']  # syntax for the same operation
+julia> ans == [1 2 [30 40] [5, 6, 7]']  # syntax for the same operation
 true
 
-julia> Float32[1 2 [30 40] [5, 6]']  # syntax for supplying the eltype
-1×6 Matrix{Float32}:
- 1.0  2.0  30.0  40.0  5.0  6.0
+julia> Float32[1 2 [30 40] [5, 6, 7]']  # syntax for supplying the eltype
+1×7 Matrix{Float32}:
+ 1.0  2.0  30.0  40.0  5.0  6.0  7.0
 
 julia> ms = [zeros(2,2), [1 2; 3 4], [50 60; 70 80]];
 
@@ -1918,13 +1913,10 @@ julia> stack(ms) |> summary  # disagrees on a vector of matrices
 julia> hcat(Int[], Int[], Int[])  # empty vectors, each of size (0,)
 0×3 Matrix{Int64}
 
-julia> col0 = Matrix(undef, 2, 0)  # empty matrix, size (2,0)
-2×0 Matrix{Any}
-
-julia> hcat([1.1, 9.9], col0, ms[3])
-2×3 Matrix{Any}:
- 1.1  50.0  60.0
- 9.9  70.0  80.0
+julia> hcat([1.1, 9.9], Matrix(undef, 2, 0))  # hcat with empty 2×0 Matrix
+2×1 Matrix{Any}:
+ 1.1
+ 9.9
 ```
 """
 hcat(X...) = cat(X...; dims=Val(2))
@@ -1948,23 +1940,23 @@ are increased simultaneously for each input array, filling with zero elsewhere.
 This allows one to construct block-diagonal matrices as `cat(matrices...; dims=(1,2))`,
 and their higher-dimensional analogues.
 
-The keyword also accepts `Val(dims)`.
-
 The special case `dims=1` is [`vcat`](@ref), and `dims=2` is [`hcat`](@ref).
 See also [`hvcat`](@ref), [`stack`](@ref), [`repeat`](@ref).
 
+The keyword also accepts `Val(dims)`.
+
+!!! compat "Julia 1.8"
+    For multiple dimensions `dims = Val(::Tuple)` was added in Julia 1.8.
+
 # Examples
 ```jldoctest
-julia> cat([1 2; 3 4], [pi, pi], fill(10, 2,3,1); dims=2)
+julia> cat([1 2; 3 4], [pi, pi], fill(10, 2,3,1); dims=2)  # same as hcat
 2×6×1 Array{Float64, 3}:
 [:, :, 1] =
  1.0  2.0  3.14159  10.0  10.0  10.0
  3.0  4.0  3.14159  10.0  10.0  10.0
 
-julia> size([pi, pi], 3)
-1
-
-julia> cat(true, trues(2,2), trues(4)', dims=(1,2))
+julia> cat(true, trues(2,2), trues(4)', dims=(1,2))  # block-diagonal
 4×7 Matrix{Bool}:
  1  0  0  0  0  0  0
  0  1  1  0  0  0  0