From d3189611df765a5d2eff0ed4d04b8f97fc887c5e Mon Sep 17 00:00:00 2001
From: Alex Arslan <ararslan@comcast.net>
Date: Tue, 7 Mar 2017 22:59:17 -0800
Subject: [PATCH] Doc Hard 2: Doc Harder

---
 src/abstractdataarray.jl |  6 ++--
 src/dataarray.jl         |  9 +++---
 src/natype.jl            |  4 +--
 src/statistics.jl        | 68 +++++++++++++++++++++++++++++++++++++---
 4 files changed, 73 insertions(+), 14 deletions(-)

diff --git a/src/abstractdataarray.jl b/src/abstractdataarray.jl
index df9588a..44a6df8 100644
--- a/src/abstractdataarray.jl
+++ b/src/abstractdataarray.jl
@@ -1,7 +1,7 @@
 """
     AbstractDataArray{T, N}
 
-An `AbstractArray` of order `N` whose entries can take on values of type
+An `N`-dimensional `AbstractArray` whose entries can take on values of type
 `T` or the value `NA`.
 """
 abstract type AbstractDataArray{T, N} <: AbstractArray{T, N} end
@@ -9,14 +9,14 @@ abstract type AbstractDataArray{T, N} <: AbstractArray{T, N} end
 """
     AbstractDataVector{T}
 
-An [`AbstractDataArray`](@ref) of order 1.
+A 1-dimensional [`AbstractDataArray`](@ref).
 """
 const AbstractDataVector{T} = AbstractDataArray{T, 1}
 
 """
     AbstractDataMatrix{T}
 
-An [`AbstractDataArray`](@ref) of order 2.
+A 2-dimensional [`AbstractDataArray`](@ref).
 """
 const AbstractDataMatrix{T} = AbstractDataArray{T, 2}
 
diff --git a/src/dataarray.jl b/src/dataarray.jl
index d259a3b..e0e5b8c 100644
--- a/src/dataarray.jl
+++ b/src/dataarray.jl
@@ -1,8 +1,7 @@
 # TODO: Remove some T's from output type signatures
 
 """
-    DataArray{T,N}(d::Array{T,N}, m::BitArray{N} = falses(size(d)))
-    DataArray{T,N}(d::Array{T,N}, m::Array{Bool})
+    DataArray{T,N}(d::Array{T,N}, m::AbstractArray{Bool} = falses(size(d)))
 
 Construct a `DataArray`, an `N`-dimensional array with element type `T` that allows missing
 values. The resulting array uses the data in `d` with `m` as a bitmask to signify missingness.
@@ -59,7 +58,7 @@ function DataArray{T, N}(d::Array{T, N},
     return DataArray{T, N}(d, m)
 end
 
-function DataArray(d::Array, m::Array{Bool}) # -> DataArray{T}
+function DataArray(d::Array, m::AbstractArray{Bool}) # -> DataArray{T}
     return DataArray(d, BitArray(m))
 end
 
@@ -74,14 +73,14 @@ end
 """
     DataVector{T}
 
-A `DataArray` of order 1 with element type `T`.
+A 1-dimensional `DataArray` with element type `T`.
 """
 const DataVector{T} = DataArray{T, 1}
 
 """
     DataMatrix{T}
 
-A `DataArray` of order 2 with element type `T`.
+A 2-dimensional `DataArray` with element type `T`.
 """
 const DataMatrix{T} = DataArray{T, 2}
 
diff --git a/src/natype.jl b/src/natype.jl
index 2e2cde0..53584f5 100644
--- a/src/natype.jl
+++ b/src/natype.jl
@@ -17,7 +17,7 @@
 """
     NAtype
 
-The data type of a missing value, `NA`.
+The type of a missing value, `NA`.
 """
 struct NAtype
 end
@@ -25,7 +25,7 @@ end
 """
     NA
 
-The sentinel value representing missingness.
+A value denoting missingness within the domain of any type.
 """
 const NA = NAtype()
 
diff --git a/src/statistics.jl b/src/statistics.jl
index d09598c..1f6bda5 100644
--- a/src/statistics.jl
+++ b/src/statistics.jl
@@ -1,4 +1,19 @@
 # This is multiplicative analog of diff
+"""
+    reldiff(v::Vector) -> Vector
+
+For each element in `v`, compute the relative difference from the previous element.
+
+# Examples
+
+```jldoctest
+julia> reldiff([1.0, 2.0, 3.0, 4.0])
+3-element Array{Float64,1}:
+ 2.0
+ 1.5
+ 1.33333
+```
+"""
 function reldiff{T}(v::Vector{T})
     n = length(v)
     res = Array(T, n - 1)
@@ -9,6 +24,21 @@ function reldiff{T}(v::Vector{T})
 end
 
 # Diff scaled by previous value
+"""
+    percent_change(v::Vector) -> Vector
+
+For each element in `v`, compute the percent change from the previous element.
+
+# Examples
+
+```jldoctest
+julia> percent_change([1.0, 2.0, 3.0, 4.0])
+3-element Array{Float64,1}:
+ 1.0
+ 0.5
+ 0.333333
+```
+"""
 function percent_change{T}(v::Vector{T})
     n = length(v)
     res = Array(T, n - 1)
@@ -21,7 +51,28 @@ end
 autocor{T}(dv::DataVector{T}, lag::Int) = cor(dv[1:(end - lag)], dv[(1 + lag):end])
 autocor{T}(dv::DataVector{T}) = autocor(dv, 1)
 
-# Generate levels - see the R documentation for gl
+"""
+    gl(n::Integer, k::Integer, l::Integer = n*k) -> PooledDataArray
+
+Generate a [`PooledDataArray`](@ref) with `n` levels and `k` replications, optionally
+specifying an output length `l`. If specified, `l` must be a multiple of `n*k`.
+
+# Examples
+
+```jldoctest
+julia> gl(2, 1)
+2-element DataArrays.PooledDataArray{Int64,UInt8,1}:
+ 1
+ 2
+
+julia> gl(2, 1, 4)
+4-element DataArrays.PooledDataArray{Int64,UInt8,1}:
+ 1
+ 2
+ 1
+ 2
+```
+"""
 function gl(n::Integer, k::Integer, l::Integer)
     nk = n * k
     d, r = divrem(l, nk)
@@ -35,7 +86,12 @@ end
 
 gl(n::Integer, k::Integer) = gl(n, k, n*k)
 
-# A cross-tabulation type. Currently just a one-way table
+"""
+    xtab(x::AbstractArray) -> xtab
+
+Construct a cross-tabulation table from the unique values in `x`.
+Currently only one-way tables are supported. Returns an `xtab` object.
+"""
 type xtab{T}
     vals::Array{T}
     counts::Vector{Int}
@@ -54,8 +110,12 @@ function xtab{T}(x::AbstractArray{T})
     return xtab(kk, cc)
 end
 
-# Another cross-tabulation function, this one leaves the result as a Dict
-# Again, this is currently just for one-way tables.
+"""
+    xtabs(x::AbstractArray) -> Dict
+
+Construct a cross-tabulation table from the unique values in `x`,
+returning a `Dict`. Currently only one-way tables are supported.
+"""
 function xtabs{T}(x::AbstractArray{T})
     d = Dict{T, Int}()
     for el in x