[WIP] Clean up codebase for a public 0.1.0 release

src/constructors.jl

@@ -1,47 +1,160 @@
+@doc """
+# Description
 
-# ----- Outer Constructors -------------------------------------------------- #
+Construct a NullableArray from an array of values and a Boolean mask indicating
+which values should be considered null.
 
-# ----- Constructor #1
-# The following provides an outer constructor whose argument signature matches
-# that of the inner constructor provided in 01_typedefs.jl.
-function NullableArray{T, N}(A::AbstractArray{T, N},
-                             m::Array{Bool, N}) # -> NullableArray{T, N}
-    return NullableArray{T, N}(A, m)
-end
+# Args
+
+* values: An array indicating the values taken on when entries are not null.
+* isnull: An array indicating which entries are not null.
+
+# Returns
+
+* x::NullableArray{T, N}: A nullable array containing the specified values
+    and missing the indicated entries.
 
-# ----- Constructor #2 -------------------------------------------------------#
-# Constructs a NullableArray from an Array 'a' of values and an optional
-# Array{Bool, N} mask. If omitted, the mask will default to an array of
-# 'false's the size of 'a'.
-function NullableArray{T, N}(A::AbstractArray{T, N}) # -> NullableArray{T, N}
-    return NullableArray{T, N}(A, fill(false, size(A)))
+# Examples
+
+```
+x = NullableArray([1, 2, 3], [false, false, false])
+y = NullableArray([1, 2, 3])
+```
+""" ->
+function NullableArray{T, N}(
+    values::AbstractArray{T, N},
+    isnull::Array{Bool, N} = fill(false, size(values)),
+)
+    NullableArray{T, N}(values, isnull)
 end
 
-# ----- Constructor #3 -------------------------------------------------------#
-# TODO: Uncomment this doc entry when Base Julia can parse it correctly.
-# @doc """
-# Allow users to construct a quasi-uninitialized `NullableArray` object by
-# specifing:
-#
-# * `T`: The type of its elements.
-# * `dims`: The size of the resulting `NullableArray`.
-#
-# NOTE: The `values` field will be truly uninitialized, but the `isnull` field
-# will be initialized to `true` everywhere, making every entry of a new
-# `NullableArray` a null value by default.
-# """ ->
-function NullableArray{T}(::Type{T}, dims::Dims) # -> NullableArray{T, N}
-    return NullableArray(Array(T, dims), fill(true, dims))
+@doc """
+# Description
+
+Construct a quasi-uninitialized `NullableArray` object by specifying the type
+of its elements and its size as a tuple.
+
+The result is quasi-uninitialized because the underlying memory for
+representing values will be left uninitialized, but the `isnull` bitmask will
+be initialized to false everywhere.
+
+# Args
+
+* T: The type of elements of the resulting `NullableArray`.
+* dims: The size of the resulting `NullableArray` as a tuple.
+
+# Returns
+
+* x::NullableArray{T, N}: A nullable array of the specified type and size.
+
+# Examples
+
+```
+x = NullableArray(Int64, (2, 2))
+```
+""" ->
+function NullableArray{T}(::Type{T}, dims::Dims)
+    NullableArray(Array(T, dims), fill(true, dims))
 end
 
-# ----- Constructor #4 -------------------------------------------------------#
-# Constructs an empty NullableArray of type parameter T and number of dimensions
-# equal to the number of arguments given in 'dims...', where the latter are
-# dimension lengths.
-function NullableArray(T::Type, dims::Int...) # -> NullableArray
+@doc """
+# Description
+
+Construct a quasi-uninitialized `NullableArray` object by specifying the type
+of its elements and its size as a sequence of separate integer arguments.
+
+The result is quasi-uninitialized because the underlying memory for
+representing values will be left uninitialized, but the `isnull` bitmask will
+be initialized to false everywhere.
+
+# Args
+
+* T: The type of elements of the resulting `NullableArray`.
+* dims: The size of the resulting `NullableArray` as a sequence of integer
+    arguments.
+
+# Returns
+
+* x::NullableArray{T, N}: A nullable array of the specified type and size.
+
+# Examples
+
+```
+x = NullableArray(Int64, 2, 2)
+```
+""" ->
+function NullableArray(T::Type, dims::Int...)
     return NullableArray(T, dims)
 end
 
+@doc """
+# Description
+
+Construct an empty `NullableArray` object by calling the name of the
+fully parametrized type with zero arguments.
+
+# Args
+
+NONE
+
+# Returns
+
+* x::NullableArray{T, N}: An empty nullable array of the specified type.
+
+# Examples
+
+```
+x = NullableArray{Int64, 2}()
+```
+""" ->
+function Base.call{T, N}(::Type{NullableArray{T, N}})
+    NullableArray(T, ntuple(i -> 0, N))
+end
+
+@doc """
+# Description
+
+Construct an empty `NullableVector` object by calling the name of the
+fully parametrized type with zero arguments.
+
+# Args
+
+NONE
+
+# Returns
+
+* x::NullableVector{T}: An empty nullable vector of the specified type.
+
+# Examples
+
+```
+x = NullableVector{Int64}()
+```
+""" ->
+Base.call{T}(::Type{NullableVector{T}}) = NullableArray(T, (0, ))
+
+@doc """
+# Description
+
+Construct an empty `NullableMatrix` object by calling the name of the
+fully parametrized type with zero arguments.
+
+# Args
+
+NONE
+
+# Returns
+
+* x::NullableMatrix{T}: An empty nullable matrix of the specified type.
+
+# Examples
+
+```
+x = NullableMatrix{Int64}()
+```
+""" ->
+Base.call{T}(::Type{NullableMatrix{T}}) = NullableArray(T, (0, 0))
+
 # ----- Constructor #5 -------------------------------------------------------#
 # The following method constructs a NullableArray from an Array{Any} argument
 # 'A' that contains some placeholder of type 'T' for null values.
@@ -94,12 +207,3 @@ function NullableArray{T}(A::AbstractArray,
     end
     return res
 end
-
-#----- Constructor #7 --------------------------------------------------------#
-
-# The following method allows for the construction of zero-element
-# NullableArrays by calling the parametrized type on zero arguments.
-# TODO: add support for dimensions arguments?
-function Base.call{T, N}(::Type{NullableArray{T, N}})
-    NullableArray(T, ntuple(i->0, N))
-end

src/typedefs.jl

@@ -1,22 +1,10 @@
-# === Design Notes ===
-#
-# `NullableArray{T, N}` is a struct-of-arrays representation of
-# `Array{Nullable{T}, N}`. This makes it easy to define complicated operations
-# (e.g. matrix multiplication) by reusing the existing definition for
-# `Array{T}`.
-#
-# One complication when defining functions that operate on the internal fields
-# of a `NullableArray` is that developers must take care to ensure that they
-# do not index into an undefined entry in the `values` field. This is not a
-# problem for `isbits` types, which are never `#undef`, but will trigger
-# an exception for any other type.
-#
-# TODO: Ensure that size(values) == size(isnull) using inner constructor.
-# TODO: Implement outer constructor required once we add an inner constructor.
 @doc """
 `NullableArray{T, N}` is an efficient alternative to `Array{Nullable{T}, N}`.
-It allows users to easily define operations on arrays with null values by
-reusing operations that only work on arrays without any null values.
+It allows users to define operations on arrays with null values by reusing
+operations that only work on arrays without any null values. We refer to
+such reuse as "lifting" an operation from the domain of non-nullable values
+to the domain of nullable values. Examples include lifting the definition of
+matrix multiplication from non-nullable arrays to nullable arrays.
 """ ->
 immutable NullableArray{T, N} <: AbstractArray{Nullable{T}, N}
     values::Array{T, N}
@@ -31,5 +19,12 @@ immutable NullableArray{T, N} <: AbstractArray{Nullable{T}, N}
     end
 end
 
+@doc """
+`NullableVector{T}` is an alias for `NullableArray{T, 1}`
+""" ->
 typealias NullableVector{T} NullableArray{T, 1}
+
+@doc """
+`NullableMatrix{T}` is an alias for `NullableArray{T, 2}`
+""" ->
 typealias NullableMatrix{T} NullableArray{T, 2}