wording, plus examples

stdlib/LinearAlgebra/src/matmul.jl

@@ -1089,22 +1089,39 @@ const RealOrComplex = Union{Real,Complex}
  *(A, B::AbstractMatrix, C)
  A * B * C * D
 
-Chained multiplication of 3 or 4 matrices is done in the most efficient order,
-i.e. the order which minimises the total number of scalar multiplications involved,
-based on the sizes of the arrays.
-
-If the last factor is a vector, or the first a transposed vector,
-it is efficient to do these first. In particular `x' * B * y` means `(x' * B) * y`
-for an ordinary colum-major `B`. This is usually faster than `dot(x, B, y)`,
+Chained multiplication of 3 or 4 matrices is done in the most efficient sequence,
+based on the sizes of the arrays. That is, the number of scalar multiplications needed
+for `(A * B) * C` (with 3 dense matrices) is compared to that for `A * (B * C)`
+to choose which of these to execute.
+
+If the last factor is a vector, or the first a transposed vector, then it is efficient
+to deal with these first. In particular `x' * B * y` means `(x' * B) * y`
+for an ordinary colum-major `B::Matrix`. This is often equivalent to `dot(x, B, y)`,
 although it allocates an intermediate array.
 
 If the first or last factor is a number, this will be fused with the matrix
 multiplication, using 5-arg [`mul!`](@ref).
 
-See also [`dot`](@ref), [`muladd`](@ref).
+See also [`muladd`](@ref), [`dot`](@ref).
 
 !!! compat "Julia 1.7"
  These optimisations require at least Julia 1.7.
+
+# Examples
+```
+julia> A, B, C = randn(100,10), randn(10,100), randn(100,10);
+
+julia> using BenchmarkTools
+
+julia> @btime ($A * $B) * $C; # slow
+ 13.500 μs (3 allocations: 86.14 KiB)
+
+julia> @btime $A * ($B * $C); # fast
+ 1.892 μs (2 allocations: 8.81 KiB)
+
+julia> @btime $A * $B * $C; # automatic
+ 1.896 μs (2 allocations: 8.81 KiB)
+```
 """
 *(A::AbstractMatrix, B::AbstractMatrix, x::AbstractVector) = A * (B*x)