add some docstrings (#172)

* add some docstrings

* cleanup

Author: CarloLucibello

src/conv.jl

@@ -164,18 +164,33 @@ if is_nnpack_available()
     end
 end
 
-function conv(x, w::AbstractArray{T, N}; stride = 1, pad = 0, dilation = 1, flipped = false) where {T, N}
+"""
+    conv(x, w; stride=1, pad=0, dilation=1, flipped=false)
+
+Apply convolution filter `w` to input `x`. `x` and `w` are 3d/4d/5d tensors 
+in 1d/2d/3d convolutions respectively. 
+"""
+function conv(x, w::AbstractArray{T, N}; stride=1, pad=0, dilation=1, flipped=false) where {T, N}
     stride = expand(Val(N-2), stride)
     pad = expand(Val(N-2), pad)
     dilation = expand(Val(N-2), dilation)
-    cdims = DenseConvDims(x, w; stride = stride, padding = pad, dilation = dilation, flipkernel = flipped)
+    cdims = DenseConvDims(x, w; stride=stride, padding=pad, dilation=dilation, flipkernel=flipped)
     return conv(x, w, cdims)
 end
 
-function depthwiseconv(x, w::AbstractArray{T, N}; stride = 1, pad = 0, dilation = 1, flipped = false) where {T, N}
+
+
+
+"""
+    depthwiseconv(x, w; stride=1, pad=0, dilation=1, flipped=false)
+
+Depthwise convolution operation with filter `w` on input `x`. `x` and `w` 
+are 3d/4d/5d tensors in 1d/2d/3d convolutions respectively. 
+"""
+function depthwiseconv(x, w::AbstractArray{T, N}; stride=1, pad=0, dilation=1, flipped=false) where {T, N}
     stride = expand(Val(N-2), stride)
     pad = expand(Val(N-2), pad)
     dilation = expand(Val(N-2), dilation)
-    cdims = DepthwiseConvDims(x, w; stride = stride, padding = pad, dilation = dilation, flipkernel = flipped)
+    cdims = DepthwiseConvDims(x, w; stride=stride, padding=pad, dilation=dilation, flipkernel=flipped)
     return depthwiseconv(x, w, cdims)
 end

src/pooling.jl

@@ -140,16 +140,28 @@ end
 expand(N, i::Tuple) = i
 expand(N, i::Integer) = ntuple(_ -> i, N)
 
-function maxpool(x, k::NTuple{N, Integer}; pad = 0, stride = k) where N
+
+"""
+    maxpool(x, k::NTuple; pad=0, stride=k)
+
+Perform max pool operation with window size `k` on input tensor `x`.
+"""
+function maxpool(x, k::NTuple{N, Integer}; pad=0, stride=k) where N
     pad = expand(Val(N), pad)
     stride = expand(Val(N), stride)
-    pdims = PoolDims(x, k; padding = pad, stride = stride)
+    pdims = PoolDims(x, k; padding=pad, stride=stride)
     return maxpool(x, pdims)
 end
 
-function meanpool(x, k::NTuple{N, Integer}; pad = 0, stride = k) where N
+
+"""
+    meanpool(x, k::NTuple; pad=0, stride=k)
+
+Perform mean pool operation with window size `k` on input tensor `x`.
+"""
+function meanpool(x, k::NTuple{N, Integer}; pad=0, stride=k) where N
     pad = expand(Val(N), pad)
     stride = expand(Val(N), stride)
-    pdims = PoolDims(x, k; padding = pad, stride = stride)
+    pdims = PoolDims(x, k; padding=pad, stride=stride)
     return meanpool(x, pdims)
 end

src/softmax.jl

@@ -2,22 +2,28 @@ export softmax, softmax!, ∇softmax, ∇softmax!,
        logsoftmax, logsoftmax!, ∇logsoftmax, ∇logsoftmax!
 
 """
-    softmax(xs) = exp.(xs) ./ sum(exp.(xs))
+    softmax(x; dims=1)
+    
+[Softmax](https://en.wikipedia.org/wiki/Softmax_function) turns input array `x` 
+into probability distributions that sum to 1 along the dimensions specified by `dims`.
+It is semantically equivalent to the following:
 
-[Softmax](https://en.wikipedia.org/wiki/Softmax_function) takes
-log-probabilities (any real vector) and returns a probability distribution that
-sums to 1.
+    softmax(x; dims=1) = exp.(x) ./ sum(exp.(x), dims=dims)
 
-If given a matrix it will by default (`dims=1`) treat it as a batch of vectors,
-with each column independent. Keyword `dims=2` will instead treat rows independently, etc.
+with additional manipulations enhancing numerical stability.
 
-```
-julia> softmax([1,2,3.])
+For a matrix input `x` it will by default (`dims=1`) treat it as a batch of vectors,
+with each column independent. Keyword `dims=2` will instead treat rows independently, 
+etc...
+```julia-repl
+julia> softmax([1, 2, 3])
 3-element Array{Float64,1}:
   0.0900306
   0.244728
   0.665241
 ```
+
+See also [`logsoftmax`](@ref).
 """
 function softmax(xs::AbstractArray; dims=1)
     max_ = maximum(xs, dims=dims)
@@ -64,11 +70,17 @@ end
 
 
 """
-    logsoftmax(xs) = log.(exp.(xs) ./ sum(exp.(xs)))
+    logsoftmax(x; dims=1)
 
 Computes the log of softmax in a more numerically stable
 way than directly taking `log.(softmax(xs))`. Commonly used in
 computing cross entropy loss.
+
+It is semantically equivalent to the following:
+
+    logsoftmax(x; dims=1) = x .- log.(sum(exp.(x), dims=dims))
+
+See also [`softmax`](@ref).
 """
 function logsoftmax(xs::AbstractArray; dims=1)
     max_ = maximum(xs, dims=dims)