expands docs for fftshift and ifftshift (#17)

Author: ssfrr

src/definitions.jl

@@ -363,11 +363,19 @@ plan_irfft
 fftshift(x) = circshift(x, div.([size(x)...],2))
 
 """
-    fftshift(x)
+    fftshift(x, [dim])
 
-Swap the first and second halves of each dimension of `x`.
+Circular-shift along the given dimension of a periodic signal `x` centered at
+index `1` so it becomes centered at index `N÷2+1`, where `N` is the size of
+that dimension.
+
+This can be undone with [`ifftshift`](@ref). For even `N` this is equivalent to
+swapping the first and second halves, so `fftshift` and [`ifftshift`](@ref) are
+the same.
+
+If `dim` is not given then the signal is shifted along each dimension.
 """
-fftshift(x)
+fftshift
 
 function fftshift(x,dim)
     s = zeros(Int,ndims(x))
@@ -377,19 +385,20 @@ function fftshift(x,dim)
     circshift(x, s)
 end
 
-"""
-    fftshift(x,dim)
-
-Swap the first and second halves of the given dimension or iterable of dimensions of array `x`.
-"""
-fftshift(x,dim)
-
 ifftshift(x) = circshift(x, div.([size(x)...],-2))
 
 """
     ifftshift(x, [dim])
 
-Undoes the effect of `fftshift`.
+Circular-shift along the given dimension of a periodic signal `x` centered at
+index `N÷2+1` so it becomes centered at index `1`, where `N` is the size of
+that dimension.
+
+This undoes the effect of [`fftshift`](@ref). For even `N` this is equivalent to
+swapping the first and second halves, so [`fftshift`](@ref) and `ifftshift` are
+the same.
+
+If `dim` is not given then the signal is shifted along each dimension.
 """
 ifftshift