Document @. exceptions for ' and :

base/broadcast.jl

@@ -1282,6 +1282,10 @@ If you want to *avoid* adding dots for selected function calls in
 `@. sqrt(abs(\$sort(x)))` is equivalent to `sqrt.(abs.(sort(x)))`
 (no dot for `sort`).
 
+Note that the postfix `'` and infix `:` operators don't have a broadcasted
+version (`.'` and `.:` are not valid operators), and are not affected by `@.`.
+The dot operator for property access as in `a.x` is also unaffected.
+
 (`@.` is equivalent to a call to `@__dot__`.)
 
 # Examples
@@ -1294,6 +1298,18 @@ julia> @. y = x + 3 * sin(x)
  4.727892280477045
  3.4233600241796016
 ```
+
+The postfix `'` being unaffected by `@.` can be convenient to broadcast vectors
+along different dimensions:
+
+```jldoctest
+julia> @. (10:10:30) + (1:4)'
+3×4 Matrix{Int64}:
+ 11  12  13  14
+ 21  22  23  24
+ 31  32  33  34
+```
+
 """
 macro __dot__(x)
     esc(__dot__(x))

doc/src/manual/functions.md

@@ -1122,7 +1122,7 @@ so that the left-hand side is updated in-place.
 
 Since adding dots to many operations and function calls in an expression
 can be tedious and lead to code that is difficult to read, the macro
-[`@.`](@ref @__dot__) is provided to convert *every* function call,
+[`@.`](@ref @__dot__) is provided to convert every function call,
 operation, and assignment in an expression into the "dotted" version.
 
 ```jldoctest

doc/src/manual/mathematical-operations.md

@@ -168,7 +168,7 @@ The updating versions of all the binary arithmetic and bitwise operators are:
 
 ## [Vectorized "dot" operators](@id man-dot-operators)
 
-For *every* binary operation like `^`, there is a corresponding
+For every binary operation like `^`, there is a corresponding
 "dot" operation `.^` that is *automatically* defined
 to perform `^` element-by-element on arrays. For example,
 `[1, 2, 3] ^ 3` is not defined, since there is no standard
@@ -213,6 +213,25 @@ For example, it is not clear whether `1.+x` means `1. + x` or `1 .+ x`.
 Therefore this syntax is disallowed, and spaces must be used around
 the operator in such cases.
 
+There are some exceptions to the above rules: the postfix adjoint operator `'`,
+the infix range operator `:` and the property access operator `.` don't have a
+dotted version (they can still be broadcasted using the function call syntax as
+in `adjoint.(A)`, `(:).(a, b)` and `getproperty.(a, x)`). These operators are
+also unaffected by the `@.` macro. In the case of `'` this can be convenient to
+broadcast vectors along different
+dimensions:
+
+```jldoctest
+julia> x = 1:3;
+
+julia> y = 1:2;
+
+julia> z = @. x'^2 + y^2
+2×3 Matrix{Int64}:
+ 2  5  10
+ 5  8  13
+```
+
 ## Numeric Comparisons
 
 Standard comparison operations are defined for all the primitive numeric types: