From cc34b95121c2f082b6d5e7093b091e1f3792fde2 Mon Sep 17 00:00:00 2001
From: Katharine Hyatt <kshyatt@users.noreply.github.com>
Date: Sat, 3 Sep 2016 10:33:08 -0700
Subject: [PATCH] Merge pull request #18041 from JuliaLang/ksh/docamputation

Moved so many docs out of HelpDB. More examples.
---
 src/dsp.jl | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/src/dsp.jl b/src/dsp.jl
index 43ec694..8341e6f 100644
--- a/src/dsp.jl
+++ b/src/dsp.jl
@@ -8,6 +8,12 @@ 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)
@@ -15,6 +21,13 @@ 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