doc strings type and add trait inheritance section (#186)

* doc strings type and add trait inheritance section
* Add consistent type return annotation to doc strings (where
  appropriate)
* Section on inheriting behavior using `parent_type`.
* Put doc strings in manual after text
* Add dimension section to docs

Author: Tokazama

docs/src/index.md

@@ -4,13 +4,32 @@ CurrentModule = ArrayInterface
 
 # ArrayInterface
 
-```@index
-```
+Designs for new Base array interface primitives, used widely through scientific machine learning (SciML) and other organizations
 
-```@autodocs
-Modules = [ArrayInterface]
+## Inheriting Array Traits
+
+Creating an array type with unique behavior in Julia is often accomplished by creating a lazy wrapper around previously defined array types.
+This allows the new array type to inherit functionality by redirecting methods to the parent array (e.g., `Base.size(x::Wrapper) = size(parent(x))`).
+Generic design limits the need to define an excessive number of methods like this.
+However, methods used to describe a type's traits often need to be explicitly defined for each trait method.
+`ArrayInterface` assists with this by providing information about the parent type using [`ArrayInterface.parent_type`](@ref).
+By default `ArrayInterface.parent_type(::Type{T})` returns `T` (analogous to `Base.parent(x) = x`).
+If any type other than `T` is returned we assume `T` wraps a parent structure, so methods know to unwrap instances of `T`.
+It is also assumed that if `T` has a parent type `Base.parent` is defined.
+
+For those authoring new trait methods, this may change the default definition from `has_trait(::Type{T}) where {T} = false`, to:
+```julia
+function has_trait(::Type{T}) where {T}
+    if parent_type(T) <:T
+        return false
+    else
+        return has_trait(parent_type(T))
+    end
+end
 ```
 
+Most traits in `ArrayInterface` are a variant on this pattern.
+
 ## Static Traits
 
 The size along one or more dimensions of an array may be known at compile time. 
@@ -50,3 +69,36 @@ Generic support for `ArrayInterface.known_size` relies on calling `known_length`
 Therefore, the recommended approach for supporting static sizing in newly defined array types is defining a new `axes_types` method.
 
 Static information related to subtypes of `AbstractRange` include `known_length`, `known_first`, `known_step`, and `known_last`.
+
+## Dimensions
+
+Methods such as `size(x, dim)` need to map `dim` to the dimensions of `x`.
+Typically, `dim` is an `Int` with an invariant mapping to the dimensions of `x`.
+Some methods accept `:` or a tuple of dimensions as an argument.
+`ArrayInterface` also considers `StaticInt` a viable dimension argument.
+
+[`ArrayInterface.to_dims`](@ref) helps ensure that `dim` is converted to a viable dimension mapping in a manner that helps with type stability.
+For example, all `Integers` passed to `to_dims` are converted to `Int` (unless `dim` is a `StaticInt`).
+This is also useful for arrays that uniquely label dimensions, in which case `to_dims` serves as a safe point of hooking into existing methods with dimension arguments.
+`ArrayInterface` also defines native `Symbol` to `Int` and `StaticSymbol` to `StaticInt` mapping  for arrays defining [`ArrayInterface.dimnames`](@ref).
+
+Methods accepting dimension specific arguments should use some variation of the following pattern.
+
+```julia
+f(x, dim) = f(x, ArrayInterface.to_dims(x, dim))
+f(x, dim::Int) = ...
+f(x, dim::StaticInt) = ...
+```
+
+If `x`'s first dimension is named `:dim_1` then calling `f(x, :dim_1)` would result in `f(x, 1)`.
+If users knew they always wanted to call `f(x, 2)` then they could define `h(x) = f(x, static(2))`, ensuring `f` passes along that information while compiling.
+
+## API
+
+```@index
+```
+
+```@autodocs
+Modules = [ArrayInterface]
+```
+

src/ArrayInterface.jl

@@ -52,7 +52,7 @@ const LoTri{T,M} = Union{LowerTriangular{T,M},UnitLowerTriangular{T,M}}
 include("array_index.jl")
 
 """
-    parent_type(::Type{T})
+    parent_type(::Type{T}) -> Type
 
 Returns the parent array that type `T` wraps.
 """
@@ -82,7 +82,7 @@ _has_parent(::Type{T}, ::Type{T}) where {T} = False()
 _has_parent(::Type{T1}, ::Type{T2}) where {T1,T2} = True()
 
 """
-    known_length(::Type{T})
+    known_length(::Type{T}) -> Union{Int,Nothing}
 
 If `length` of an instance of type `T` is known at compile time, return it.
 Otherwise, return `nothing`.
@@ -119,7 +119,7 @@ can_change_size(::Type{<:Base.ImmutableDict}) = false
 function ismutable end
 
 """
-    ismutable(x::DataType)
+    ismutable(x::DataType) -> Bool
 
 Query whether a type is mutable or not, see
 https://github.com/JuliaDiffEq/RecursiveArrayTools.jl/issues/19.
@@ -168,7 +168,7 @@ function Base.setindex(x::AbstractMatrix, v, i::Int, j::Int)
 end
 
 """
-    can_setindex(x::DataType)
+    can_setindex(x::DataType) -> Bool
 
 Query whether a type can use `setindex!`.
 """
@@ -208,7 +208,7 @@ A scalar `setindex!` which is always allowed.
 allowed_setindex!(x, v, i...) = Base.setindex!(x, v, i...)
 
 """
-    isstructured(x::DataType)
+    isstructured(x::DataType) -> Bool
 
 Query whether a type is a representation of a structured matrix.
 """
@@ -224,7 +224,7 @@ isstructured(::Bidiagonal) = true
 isstructured(::Diagonal) = true
 
 """
-    has_sparsestruct(x::AbstractArray)
+    has_sparsestruct(x::AbstractArray) -> Bool
 
 Determine whether `findstructralnz` accepts the parameter `x`.
 """
@@ -238,7 +238,7 @@ has_sparsestruct(x::Type{<:Tridiagonal}) = true
 has_sparsestruct(x::Type{<:SymTridiagonal}) = true
 
 """
-    issingular(A::AbstractMatrix)
+    issingular(A::AbstractMatrix) -> Bool
 
 Determine whether a given abstract matrix is singular.
 """
@@ -354,7 +354,7 @@ Returns the number.
 lu_instance(a::Any) = lu(a, check = false)
 
 """
-safevec(v)
+    safevec(v)
 
 It is a form of `vec` which is safe for all values in vector spaces, i.e., if it
 is already a vector, like an AbstractVector or Number, it will return said
@@ -409,7 +409,7 @@ struct CPUIndex <: AbstractCPU end
 struct GPU <: AbstractDevice end
 
 """
-    device(::Type{T})
+    device(::Type{T}) -> AbstractDevice
 
 Indicates the most efficient way to access elements from the collection in low-level code.
 For `GPUArrays`, will return `ArrayInterface.GPU()`.
@@ -617,7 +617,7 @@ end
 
 
 """
-    is_lazy_conjugate(::AbstractArray)
+    is_lazy_conjugate(::AbstractArray) -> Bool
 
 Determine if a given array will lazyily take complex conjugates, such as with `Adjoint`. This will work with
 nested wrappers, so long as there is no type in the chain of wrappers such that `parent_type(T) == T`

src/axes.jl

@@ -1,8 +1,9 @@
 
 """
-    axes_types(::Type{T}, dim)
+    axes_types(::Type{T}) -> Type{Tuple{Vararg{AbstractUnitRange{Int}}}}
+    axes_types(::Type{T}, dim) -> Type{AbstractUnitRange{Int}}
 
-Returns the axis type along dimension `dim`.
+Returns the type of each axis for the `T`, or the type of of the axis along dimension `dim`.
 """
 axes_types(x, dim) = axes_types(typeof(x), dim)
 @inline axes_types(::Type{T}, dim) where {T} = axes_types(T, to_dims(T, dim))
@@ -21,11 +22,6 @@ end
     end
 end
 
-"""
-    axes_types(::Type{T}) -> Type
-
-Returns the type of the axes for `T`
-"""
 axes_types(x) = axes_types(typeof(x))
 axes_types(::Type{T}) where {T<:Array} = Tuple{Vararg{OneTo{Int},ndims(T)}}
 function axes_types(::Type{T}) where {T}
@@ -115,11 +111,6 @@ similar_type(::Type{OptionallyStaticUnitRange{One,StaticInt{N}}}, ::Type{Int}, :
 similar_type(::Type{OptionallyStaticUnitRange{One,StaticInt{N}}}, ::Type{Int}, ::Type{OptionallyStaticUnitRange{One,Int}}) where {N} = OptionallyStaticUnitRange{One,Int}
 similar_type(::Type{OptionallyStaticUnitRange{One,StaticInt{N1}}}, ::Type{Int}, ::Type{OptionallyStaticUnitRange{One,StaticInt{N2}}}) where {N1,N2} = OptionallyStaticUnitRange{One,StaticInt{N2}}
 
-"""
-    axes(A, d)
-
-Return a valid range that maps to each index along dimension `d` of `A`.
-"""
 @inline axes(a, dim) = axes(a, to_dims(a, dim))
 @inline axes(a, dims::Tuple{Vararg{Any,K}}) where {K} = (axes(a, first(dims)), axes(a, tail(dims))...)
 @inline axes(a, dims::Tuple{T}) where {T} = (axes(a, first(dims)), )
@@ -157,9 +148,10 @@ end
 @inline _axes(A::Base.ReshapedArray, dim::Integer) = Base.axes(A, Int(dim))  # TODO implement ArrayInterface version
 
 """
-    axes(A)
+    axes(A) -> Tuple{Vararg{AbstractUnitRange{Int}}}
+    axes(A, dim) -> AbstractUnitRange{Int}
 
-Return a tuple of ranges where each range maps to each element along a dimension of `A`.
+Returns the axis associated with each dimension of `A` or dimension `dim`
 """
 @inline function axes(a::A) where {A}
     if parent_type(A) <: A

src/dimensions.jl

@@ -37,7 +37,7 @@ _ndims_index(::Type{I}, i::StaticInt) where {I} = ndims_index(_get_tuple(I, i))
 ndims_index(::Type{I}) where {N,I<:Tuple{Vararg{Any,N}}} = eachop(_ndims_index, nstatic(Val(N)), I)
 
 """
-    from_parent_dims(::Type{T})::Tuple{Vararg{Union{Int,StaticInt}}}
+    from_parent_dims(::Type{T}) -> Tuple{Vararg{Union{Int,StaticInt}}}
 
 Returns the mapping from parent dimensions to child dimensions.
 """
@@ -72,7 +72,7 @@ function from_parent_dims(::Type{R}) where {T,N,S,A,R<:ReinterpretArray{T,N,S,A}
 end
 
 """
-    from_parent_dims(::Type{T}, dim)::Union{Int,StaticInt}
+    from_parent_dims(::Type{T}, dim) -> Union{Int,StaticInt}
 
 Returns the mapping from child dimensions to parent dimensions.
 """
@@ -98,7 +98,7 @@ function from_parent_dims(::Type{T}, ::StaticInt{dim}) where {T,dim}
 end
 
 """
-    to_parent_dims(::Type{T})::Tuple{Vararg{Union{Int,StaticInt}}}
+    to_parent_dims(::Type{T}) -> Tuple{Vararg{Union{Int,StaticInt}}}
 
 Returns the mapping from child dimensions to parent dimensions.
 """
@@ -130,7 +130,7 @@ function to_parent_dims(::Type{R}) where {T,N,S,A,R<:ReinterpretArray{T,N,S,A}}
 end
 
 """
-    to_parent_dims(::Type{T}, dim)::Union{Int,StaticInt}
+    to_parent_dims(::Type{T}, dim) -> Union{Int,StaticInt}
 
 Returns the mapping from child dimensions to parent dimensions.
 """
@@ -156,7 +156,7 @@ function to_parent_dims(::Type{T}, ::StaticInt{dim}) where {T,dim}
 end
 
 """
-    has_dimnames(::Type{T})::Bool
+    has_dimnames(::Type{T}) -> Bool
 
 Returns `true` if `x` has names for each dimension.
 """
@@ -173,8 +173,8 @@ end
 const SUnderscore = StaticSymbol(:_)
 
 """
-    dimnames(::Type{T})::Tuple{Vararg{StaticSymbol}}
-    dimnames(::Type{T}, dim)::StaticSymbol
+    dimnames(::Type{T}) -> Tuple{Vararg{StaticSymbol}}
+    dimnames(::Type{T}, dim) -> StaticSymbol
 
 Return the names of the dimensions for `x`.
 """
@@ -204,7 +204,7 @@ function dimnames(::Type{T}) where {T<:SubArray}
 end
 
 """
-    to_dims(::Type{T}, dim)::Union{Int,StaticInt}
+    to_dims(::Type{T}, dim) -> Union{Int,StaticInt}
 
 This returns the dimension(s) of `x` corresponding to `d`.
 """

src/indexing.jl

@@ -1,6 +1,6 @@
 
 """
-    is_canonical(::Type{I})::StaticBool
+    is_canonical(::Type{I}) -> StaticBool
 
 Returns `True` if instances of `I` can be used for indexing without any further change
 (e.g., `Int`, `StaticInt`, `UnitRange{Int}`)
@@ -43,7 +43,7 @@ is_linear_indexing(A, args::Tuple{Arg}) where {Arg} = ndims_index(Arg) < 2
 is_linear_indexing(A, args::Tuple{Arg,Vararg{Any}}) where {Arg} = false
 
 """
-    to_indices(A, inds::Tuple)::Tuple
+    to_indices(A, inds::Tuple) -> Tuple
 
 Maps indexing arguments `inds` to the axes of `A`, ensures they are converted to a native
 indexing form, and that they are inbounds. Unless all indices in `inds` return `static(true)`
@@ -255,7 +255,7 @@ function unsafe_reconstruct(A::AbstractUnitRange, data; kwargs...)
 end
 
 """
-    to_axes(A, inds)
+    to_axes(A, inds) -> Tuple
 
 Construct new axes given the corresponding `inds` constructed after
 `to_indices(A, args) -> inds`. This method iterates through each pair of axes and

src/ranges.jl

@@ -1,6 +1,6 @@
 
 """
-    known_first(::Type{T})
+    known_first(::Type{T}) -> Union{Int,Nothing}
 
 If `first` of an instance of type `T` is known at compile time, return it.
 Otherwise, return `nothing`.
@@ -24,7 +24,7 @@ end
 known_first(::Type{Base.OneTo{T}}) where {T} = one(T)
 
 """
-    known_last(::Type{T})
+    known_last(::Type{T}) -> Union{Int,Nothing}
 
 If `last` of an instance of type `T` is known at compile time, return it.
 Otherwise, return `nothing`.
@@ -48,7 +48,7 @@ function known_last(::Type{T}) where {T}
 end
 
 """
-    known_step(::Type{T})
+    known_step(::Type{T}) -> Union{Int,Nothing}
 
 If `step` of an instance of type `T` is known at compile time, return it.
 Otherwise, return `nothing`.
@@ -572,14 +572,14 @@ end
 end
 
 """
-    indices(x, dim)
+    indices(x, dim) -> AbstractUnitRange{Int}
 
 Given an array `x`, this returns the indices along dimension `dim`.
 """
 @inline indices(x, d) = indices(axes(x, d))
 
 """
-    indices(x) -> AbstractUnitRange
+    indices(x) -> AbstractUnitRange{Int}
 
 Returns valid indices for the entire length of `x`.
 """
@@ -594,7 +594,7 @@ end
 @inline indices(x::AbstractUnitRange{<:Integer}) = Base.Slice(OptionallyStaticUnitRange(x))
 
 """
-    indices(x::Tuple) -> AbstractUnitRange
+    indices(x::Tuple) -> AbstractUnitRange{Int}
 
 Returns valid indices for the entire length of each array in `x`.
 """
@@ -604,7 +604,7 @@ Returns valid indices for the entire length of each array in `x`.
 end
 
 """
-    indices(x::Tuple, dim) -> AbstractUnitRange
+    indices(x::Tuple, dim)  -> AbstractUnitRange{Int}
 
 Returns valid indices for each array in `x` along dimension `dim`
 """
@@ -614,7 +614,7 @@ Returns valid indices for each array in `x` along dimension `dim`
 end
 
 """
-    indices(x::Tuple, dim::Tuple) -> AbstractUnitRange
+    indices(x::Tuple, dim::Tuple) -> AbstractUnitRange{Int}
 
 Returns valid indices given a tuple of arrays `x` and tuple of dimesions for each
 respective array (`dim`).
@@ -625,7 +625,7 @@ respective array (`dim`).
 end
 
 """
-    indices(x, dim::Tuple) -> Tuple{Vararg{AbstractUnitRange}}
+    indices(x, dim::Tuple) -> Tuple{Vararg{AbstractUnitRange{Int}}}
 
 Returns valid indices for array `x` along each dimension specified in `dim`.
 """