Merge pull request #76 from mkg33/master

Documentation changes

Author: ChrisRackauckas

README.md

@@ -5,11 +5,11 @@
 
 Julia has only recently reached v1.0 and the AbstractArray interface is still
 quite new. The purpose of this library is to solidify extensions to the current
-AbstractArray interface which are put to use in package ecosystems like
+AbstractArray interface, which are put to use in package ecosystems like
 DifferentialEquations.jl. Since these libraries are live, this package will
-serve as a staging ground for ideas before they merged into Base Julia. For this
-reason, no functionality is exported so that way if such functions are added
-and exported in a future Base Julia there will be no issues with the upgrade.
+serve as a staging ground for ideas before they are merged into Base Julia. For this
+reason, no functionality is exported so that if such functions are added
+and exported in a future Base Julia, there will be no issues with the upgrade.
 
 ## parent_type(x)
 
@@ -23,14 +23,14 @@ such as `pop!` and `popfirst!` are available for collections of type `T`.
 ## indices(x[, d])
 
 Given an array `x`, this returns the indices along dimension `d`. If `x` is a tuple
-of arrays then the indices corresponding to dimension `d` of all arrays in `x` are
-returned. If any indices are not equal along dimension `d` an error is thrown. A
+of arrays, then the indices corresponding to dimension `d` of all arrays in `x` are
+returned. If any indices are not equal along dimension `d`, an error is thrown. A
 tuple may be used to specify a different dimension for each array. If `d` is not
-specified then indices for visiting each index of `x` is returned.
+specified, then indices for visiting each index of `x` are returned.
 
 ## ismutable(x)
 
-A trait function for whether `x` is a mutable or immutable array. Used for
+A trait function for whether `x` is a mutable or an immutable array. Used for
 dispatching to in-place and out-of-place versions of functions.
 
 ## aos_to_soa(x)
@@ -43,16 +43,16 @@ A trait function for whether a matrix `x` is a sparse structured matrix.
 
 ## can_setindex(x)
 
-A trait function for whether an array `x` can use `setindex!`
+A trait function for whether an array `x` can use `setindex!`.
 
 ## has_sparsestruct(x)
 
-Determine whether `findstructralnz` accepts the parameter `x`
+Determine whether `findstructralnz` accepts the parameter `x`.
 
 ## findstructralnz(x)
 
 Returns iterators `(I,J)` of the non-zeros in the structure of the matrix `x`.
-The same as the to first two elements of `findnz(::SparseMatrixCSC)`
+The same as the first two elements of `findnz(::SparseMatrixCSC)`.
 
 ## fast_matrix_colors(A)
 
@@ -61,7 +61,7 @@ A trait function for whether `matrix_colors(A)` is a fast algorithm or a slow
 
 ## matrix_colors(A)
 
-Returns an array of for the sparsity colors of a matrix type `A`. Also includes
+Returns an array for the sparsity colors of a matrix type `A`. Also includes
 an abstract type `ColoringAlgorithm` for `matrix_colors(A,alg::ColoringAlgorithm)`
 of non-structured matrices.
 
@@ -79,16 +79,16 @@ A `setindex!` which is always allowed.
 
 ## lu_instance(A)
 
-Return an instance of the LU factorization object with the correct type
+Returns an instance of the LU factorization object with the correct type
 cheaply.
 
 ## issingular(A)
 
-Return an instance of the LU factorization object with the correct type cheaply.
+Returns an instance of the LU factorization object with the correct type cheaply.
 
 ## safevec(v)
 
-Is a form of `vec` which is safe for all values in vector spaces, i.e. if
+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
 AbstractVector or Number.
 
@@ -97,18 +97,18 @@ AbstractVector or Number.
 Creates the zero'd matrix version of `u`. Note that this is unique because
 `similar(u,length(u),length(u))` returns a mutable type, so is not type-matching,
 while `fill(zero(eltype(u)),length(u),length(u))` doesn't match the array type,
-i.e. you'll get a CPU array from a GPU array. The generic fallback is
-`u .* u' .* false` which works on a surprising number of types, but can be broken
-with weird (recursive) broadcast overloads. For higher order tensors, this
-returns the matrix linear operator type which acts on the `vec` of the array.
+i.e., you'll get a CPU array from a GPU array. The generic fallback is
+`u .* u' .* false`, which works on a surprising number of types, but can be broken
+with weird (recursive) broadcast overloads. For higher-order tensors, this
+returns the matrix linear operator type, which acts on the `vec` of the array.
 
 ## restructure(x,y)
 
 Restructures the object `y` into a shape of `x`, keeping its values intact. For
-simple objects like an `Array`, this simply amounts to a reshape. However, for
+simple objects, like an `Array`, this simply amounts to a reshape. However, for
 more complex objects such as an `ArrayPartition`, not all of the structural
 information is adequately contained in the type for standard tools to work. In
-these cases, `restructure` gives a way to convert for example an `Array` into
+these cases, `restructure` gives a way to convert, for example, an `Array` into
 a matching `ArrayPartition`.
 
 ## known_first(::Type{T})
@@ -136,8 +136,8 @@ Otherwise, return `nothing`.
 
 ## device(::Type{T})
 
-Indicates the most efficient way to access elements from the collection in low level code.
-For `GPUArrays`, will return `ArrayInterface.GPU()`.
+Indicates the most efficient way to access elements from the collection in low-level code.
+For `GPUArrays`, returns `ArrayInterface.GPU()`.
 For `AbstractArray` supporting a `pointer` method, returns `ArrayInterface.CPUPointer()`.
 For other `AbstractArray`s and `Tuple`s, returns `ArrayInterface.CPUIndex()`.
 Otherwise, returns `nothing`.
@@ -155,21 +155,21 @@ Returns a tuple of boolean `Val`s indicating whether that axis is contiguous.
 ## contiguous_batch_size(::Type{T})
 
 Returns the size of contiguous batches if `!isone(stride_rank(T, contiguous_axis(T)))`.
-If `isone(stride_rank(T, contiguous_axis(T)))`, then it will return `ContiguousBatch{0}()`.
-If `contiguous_axis(T) == -1`, it will return `ContiguousBatch{-1}()`.
-If unknown, it will return `nothing`.
+If `isone(stride_rank(T, contiguous_axis(T)))`, then returns `ContiguousBatch{0}()`.
+If `contiguous_axis(T) == -1`, returns `ContiguousBatch{-1}()`.
+If unknown, returns `nothing`.
 
 ## stride_rank(::Type{T})
 
 Returns the rank of each stride.
 
 ## dense_dims(::Type{T})
 Returns a tuple of indicators for whether each axis is dense.
-An axis `i` of array `A` is dense if `stride(A, i) * size(A, i) == stride(A, j)` where `j` is the axis (if it exists) such that `stride_rank(A)[i] + 1 == stride_rank(A)[j]`.
+An axis `i` of array `A` is dense if `stride(A, i) * size(A, i) == stride(A, j)`, where `j` is the axis (if it exists) such that `stride_rank(A)[i] + 1 == stride_rank(A)[j]`.
 
 ## ArrayInterface.size(A)
 
-Returns the size of `A`. If the size of any axes are known at compile time,
+Returns the size of `A`. If the sizes of any axes are known at compile time,
 these should be returned as `StaticInt`s. For example:
 ```julia
 julia> using StaticArrays, ArrayInterface
@@ -207,7 +207,7 @@ Is the function `f` whitelisted for `LoopVectorization.@avx`?
 Creates a static integer with value known at compile time. It is a number,
 supporting basic arithmetic. Many operations with two `StaticInt` integers
 will produce another `StaticInt` integer. If one of the arguments to a
-function call isn't static (e.g., `StaticInt(4) + 3`) then the `StaticInt`
+function call isn't static (e.g., `StaticInt(4) + 3`), then the `StaticInt`
 number will promote to a dynamic value.
 
 # List of things to add
@@ -242,5 +242,5 @@ development.
 `Base.@pure ismutable(array::AbstractArray) = typeof(array).mutable`, but there are a lot of cases
 where this tends to not work out in a way one would expect. For example, if you put a normal array
 into an immutable struct that adds more information to it, this is considered immutable, even if
-all of the `setindex!` methods work (by forwarding to the mutable array). Thus it seems safer to just
+all of the `setindex!` methods work (by forwarding to the mutable array). Thus, it seems safer to just
 always assume mutability is standard for an array, and allow arrays to opt-out.

src/ArrayInterface.jl

@@ -110,7 +110,7 @@ end
 """
     can_setindex(x::DataType)
 
-Query whether a type can use `setindex!`
+Query whether a type can use `setindex!`.
 """
 can_setindex(x) = true
 can_setindex(x::AbstractArray) = can_setindex(typeof(x))
@@ -119,14 +119,14 @@ can_setindex(::Type{<:AbstractRange}) = false
 """
     aos_to_soa(x)
 
-Converts an array of structs formulation to a struct of array
+Converts an array of structs formulation to a struct of array.
 """
 aos_to_soa(x) = x
 
 """
     fast_scalar_indexing(x)
 
-Query whether an array type has fast scalar indexing
+Query whether an array type has fast scalar indexing.
 """
 fast_scalar_indexing(x) = true
 fast_scalar_indexing(x::AbstractArray) = fast_scalar_indexing(typeof(x))
@@ -136,21 +136,21 @@ fast_scalar_indexing(::Type{<:LinearAlgebra.LQPackedQ}) = false
 """
     allowed_getindex(x,i...)
 
-A scalar getindex which is always allowed
+A scalar `getindex` which is always allowed.
 """
 allowed_getindex(x,i...) = x[i...]
 
 """
     allowed_setindex!(x,v,i...)
 
-A scalar setindex! which is always allowed
+A scalar `setindex!` which is always allowed.
 """
 allowed_setindex!(x,v,i...) = Base.setindex!(x,v,i...)
 
 """
     isstructured(x::DataType)
 
-Query whether a type is a representation of a structured matrix
+Query whether a type is a representation of a structured matrix.
 """
 isstructured(x) = false
 isstructured(x::AbstractArray) = isstructured(typeof(x))
@@ -166,7 +166,7 @@ isstructured(::Diagonal) = true
 """
     has_sparsestruct(x::AbstractArray)
 
-Determine whether `findstructralnz` accepts the parameter `x`
+Determine whether `findstructralnz` accepts the parameter `x`.
 """
 has_sparsestruct(x) = false
 has_sparsestruct(x::AbstractArray) = has_sparsestruct(typeof(x))
@@ -200,7 +200,7 @@ diaganyzero(A) = any(iszero, view(A, diagind(A)))
     findstructralnz(x::AbstractArray)
 
 Return: (I,J) #indexable objects
-Find sparsity pattern of special matrices, the same as the first two elements of findnz(::SparseMatrixCSC)
+Find sparsity pattern of special matrices, the same as the first two elements of findnz(::SparseMatrixCSC).
 """
 function findstructralnz(x::Diagonal)
   n = Base.size(x,1)
@@ -448,7 +448,7 @@ fast_matrix_colors(A::Type{<:Union{Diagonal,Bidiagonal,Tridiagonal,SymTridiagona
     matrix_colors(A::Union{Array,UpperTriangular,LowerTriangular})
 
 The color vector for dense matrix and triangular matrix is simply
-`[1,2,3,..., Base.size(A,2)]`
+`[1,2,3,..., Base.size(A,2)]`.
 """
 function matrix_colors(A::Union{Array,UpperTriangular,LowerTriangular})
     eachindex(1:Base.size(A,2)) # Vector Base.size matches number of rows
@@ -473,7 +473,7 @@ end
 """
   lu_instance(A) -> lu_factorization_instance
 
-Return an instance of the LU factorization object with the correct type
+Returns an instance of the LU factorization object with the correct type
 cheaply.
 """
 function lu_instance(A::Matrix{T}) where T
@@ -487,21 +487,21 @@ end
 """
   lu_instance(a::Number) -> a
 
-Return the number.
+Returns the number.
 """
 lu_instance(a::Number) = a
 
 """
     lu_instance(a::Any) -> lu(a, check=false)
 
-Return the number.
+Returns the number.
 """
 lu_instance(a::Any) = lu(a, check=false)
 
 """
 safevec(v)
 
-Is a form of `vec` which is safe for all values in vector spaces, i.e. if
+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
 AbstractVector or Number.
 """
@@ -513,11 +513,11 @@ safevec(v::AbstractVector) = v
 zeromatrix(u::AbstractVector)
 
 Creates the zero'd matrix version of `u`. Note that this is unique because
-`similar(u,length(u),length(u))` returns a mutable type, so is not type-matching,
+`similar(u,length(u),length(u))` returns a mutable type, so it is not type-matching,
 while `fill(zero(eltype(u)),length(u),length(u))` doesn't match the array type,
-i.e. you'll get a CPU array from a GPU array. The generic fallback is
-`u .* u' .* false` which works on a surprising number of types, but can be broken
-with weird (recursive) broadcast overloads. For higher order tensors, this
+i.e., you'll get a CPU array from a GPU array. The generic fallback is
+`u .* u' .* false`, which works on a surprising number of types, but can be broken
+with weird (recursive) broadcast overloads. For higher-order tensors, this
 returns the matrix linear operator type which acts on the `vec` of the array.
 """
 function zeromatrix(u)
@@ -553,7 +553,7 @@ struct GPU <: AbstractDevice end
 """
 device(::Type{T})
 
-Indicates the most efficient way to access elements from the collection in low level code.
+Indicates the most efficient way to access elements from the collection in low-level code.
 For `GPUArrays`, will return `ArrayInterface.GPU()`.
 For `AbstractArray` supporting a `pointer` method, returns `ArrayInterface.CPUPointer()`.
 For other `AbstractArray`s and `Tuple`s, returns `ArrayInterface.CPUIndex()`.
@@ -583,9 +583,10 @@ defines_strides(::Type{A}) where {A <: Union{<:Transpose,<:Adjoint,<:SubArray,<:
 """
 can_avx(f)
 
-Returns `true` if the function `f` is guaranteed to be compatible with `LoopVectorization.@avx` for supported element and array types.
-While a return value of `false` does not indicate the function isn't supported, this allows a library to conservatively apply `@avx`
-only when it is known to be safe to do so.
+Returns `true` if the function `f` is guaranteed to be compatible with
+`LoopVectorization.@avx` for supported element and array types. While a return
+value of `false` does not indicate the function isn't supported, this allows a
+library to conservatively apply `@avx` only when it is known to be safe to do so.
 
 ```julia
 function mymap!(f, y, args...)
@@ -602,7 +603,7 @@ can_avx(::Any) = false
 """
     insert(collection, index, item)
 
-Return a new instance of `collection` with `item` inserted into at the given `index`.
+Returns a new instance of `collection` with `item` inserted into at the given `index`.
 """
 Base.@propagate_inbounds function insert(collection, index, item)
   @boundscheck checkbounds(collection, index)
@@ -635,7 +636,7 @@ end
 """
     deleteat(collection, index)
 
-Return a new instance of `collection` with the item at the given `index` removed.
+Returns a new instance of `collection` with the item at the given `index` removed.
 """
 @propagate_inbounds function deleteat(collection::AbstractVector, index)
   @boundscheck if !checkindex(Bool, eachindex(collection), index)