add documentation for overwriting behaviour of in-place application of real-input fft plans

src/definitions.jl

@@ -356,6 +356,25 @@ plan_irfft(x::AbstractArray{Complex{T}}, d::Integer, region; kws...) where {T} =
 Pre-plan an optimized inverse real-input FFT, similar to [`plan_rfft`](@ref)
 except for [`irfft`](@ref) and [`brfft`](@ref), respectively. The first
 three arguments have the same meaning as for [`irfft`](@ref).
+
+!!! note
+    In contrast to plans created by [`plan_ifft`](@ref), the application of
+    this plan via `mul!(A, P, Â)` will potentially **overwrite the input array** `Â`
+    in the case of multidimensional transforms! See example below
+
+# Examples
+
+```
+julia> begin
+           A = Matrix{Float64}(undef, 5, 3)
+           Â = randn(ComplexF64, 3, 3)
+           Â_orig = copy(Â)
+           P = plan_irfft(Â, size(A, 1))
+           mul!(A, P, Â)
+           Â == Â_orig
+       end
+false
+```
 """
 plan_irfft
 
@@ -566,6 +585,25 @@ fft
 Pre-plan an optimized real-input FFT, similar to [`plan_fft`](@ref) except for
 [`rfft`](@ref) instead of [`fft`](@ref). The first two arguments, and the
 size of the transformed result, are the same as for [`rfft`](@ref).
+
+!!! note
+    In contrast to plans created by [`plan_fft`](@ref), the application of the
+    inverse of this plan via `ldiv!(A, P, Â)` will potentially **overwrite the input array**
+    `Â` in the case of multidimensional transforms! See example below
+
+# Examples
+
+```
+julia> begin
+           A = Matrix{Float64}(undef, 5, 3)
+           Â = randn(ComplexF64, 3, 3)
+           Â_orig = copy(Â)
+           P = plan_rfft(A)
+           ldiv!(A, P, Â)
+           Â == Â_orig
+       end
+false
+```
 """
 plan_rfft
 
@@ -576,5 +614,24 @@ Pre-plan an optimized real-input unnormalized transform, similar to
 [`plan_rfft`](@ref) except for [`brfft`](@ref) instead of
 [`rfft`](@ref). The first two arguments and the size of the transformed result, are
 the same as for [`brfft`](@ref).
+
+!!! note
+    In contrast to plans created by [`plan_bfft`](@ref), the application of
+    this plan via `mul!(A, P, Â)` will potentially **overwrite the input array** `Â`
+    in the case of multidimensional transforms! See example below
+
+# Examples
+
+```
+julia> begin
+           A = Matrix{Float64}(undef, 5, 3)
+           Â = randn(ComplexF64, 3, 3)
+           Â_orig = copy(Â)
+           P = plan_brfft(Â, size(A, 1))
+           mul!(A, P, Â)
+           Â == Â_orig
+       end
+false
+```
 """
 plan_brfft