Merge pull request #18041 from JuliaLang/ksh/docamputation

Moved so many docs out of HelpDB. More examples.

src/dsp.jl

@@ -8,13 +8,26 @@ export filt, filt!, deconv, conv, conv2, xcorr
 
 _zerosi(b,a,T) = zeros(promote_type(eltype(b), eltype(a), T), max(length(a), length(b))-1)
 
+"""
+ filt(b, a, x, [si])
+
+Apply filter described by vectors `a` and `b` to vector `x`, with an optional initial filter
+state vector `si` (defaults to zeros).
+"""
 function filt{T,S}(b::Union{AbstractVector, Number}, a::Union{AbstractVector, Number},
  x::AbstractArray{T}, si::AbstractArray{S}=_zerosi(b,a,T))
  filt!(Array{promote_type(eltype(b), eltype(a), T, S)}(size(x)), b, a, x, si)
 end
 
 # in-place filtering: returns results in the out argument, which may shadow x
 # (and does so by default)
+
+"""
+ filt!(out, b, a, x, [si])
+
+Same as [`filt`](:func:`filt`) but writes the result into the `out` argument, which may
+alias the input `x` to modify it in-place.
+"""
 function filt!{T,S,N}(out::AbstractArray, b::Union{AbstractVector, Number}, a::Union{AbstractVector, Number},
  x::AbstractArray{T}, si::AbstractArray{S,N}=_zerosi(b,a,T))
  isempty(b) && throw(ArgumentError("filter vector b must be non-empty"))
@@ -89,6 +102,12 @@ function _filt_fir!(out, b, x, si, col)
  end
 end
 
+"""
+ deconv(b,a) -> c
+
+Construct vector `c` such that `b = conv(a,c) + r`.
+Equivalent to polynomial division.
+"""
 function deconv{T}(b::StridedVector{T}, a::StridedVector{T})
  lb = size(b,1)
  la = size(a,1)
@@ -101,6 +120,11 @@ function deconv{T}(b::StridedVector{T}, a::StridedVector{T})
  filt(b, a, x)
 end
 
+"""
+ conv(u,v)
+
+Convolution of two vectors. Uses FFT algorithm.
+"""
 function conv{T<:Base.LinAlg.BlasFloat}(u::StridedVector{T}, v::StridedVector{T})
  nu = length(u)
  nv = length(v)
@@ -121,6 +145,13 @@ conv{T<:Integer}(u::StridedVector{T}, v::StridedVector{T}) = round(Int,conv(floa
 conv{T<:Integer, S<:Base.LinAlg.BlasFloat}(u::StridedVector{T}, v::StridedVector{S}) = conv(float(u), v)
 conv{T<:Integer, S<:Base.LinAlg.BlasFloat}(u::StridedVector{S}, v::StridedVector{T}) = conv(u, float(v))
 
+"""
+ conv2(u,v,A)
+
+2-D convolution of the matrix `A` with the 2-D separable kernel generated by
+the vectors `u` and `v`.
+Uses 2-D FFT algorithm.
+"""
 function conv2{T}(u::StridedVector{T}, v::StridedVector{T}, A::StridedMatrix{T})
  m = length(u)+size(A,1)-1
  n = length(v)+size(A,2)-1
@@ -135,6 +166,11 @@ function conv2{T}(u::StridedVector{T}, v::StridedVector{T}, A::StridedMatrix{T})
  return C
 end
 
+"""
+ conv2(B,A)
+
+2-D convolution of the matrix `B` with the matrix `A`. Uses 2-D FFT algorithm.
+"""
 function conv2{T}(A::StridedMatrix{T}, B::StridedMatrix{T})
  sa, sb = size(A), size(B)
  At = zeros(T, sa[1]+sb[1]-1, sa[2]+sb[2]-1)
@@ -151,6 +187,11 @@ end
 conv2{T<:Integer}(A::StridedMatrix{T}, B::StridedMatrix{T}) = round(Int,conv2(float(A), float(B)))
 conv2{T<:Integer}(u::StridedVector{T}, v::StridedVector{T}, A::StridedMatrix{T}) = round(Int,conv2(float(u), float(v), float(A)))
 
+"""
+ xcorr(u,v)
+
+Compute the cross-correlation of two vectors.
+"""
 function xcorr(u, v)
  su = size(u,1); sv = size(v,1)
  if su < sv