Consistency in traits (mostly docs) (#191)

* Clean up documentation and trait consistency

Code changes here are mostly shifting the fall back definitions to be
called on the type (is_trait(::Type{T})=false) instead of the instance
(is_trait(x)=false). Other places I've improved consistency in doc
strings and corrected how optionally static ranges print.

* Missed this commit

* Update range doc string

Author: Tokazama

src/ArrayInterface.jl

@@ -119,13 +119,12 @@ can_change_size(::Type{<:Base.ImmutableDict}) = false
 function ismutable end
 
 """
-    ismutable(x::DataType) -> Bool
+    ismutable(::Type{T}) -> Bool
 
-Query whether a type is mutable or not, see
+Query whether instances of type `T` are mutable or not, see
 https://github.com/JuliaDiffEq/RecursiveArrayTools.jl/issues/19.
 """
 ismutable(x) = ismutable(typeof(x))
-
 function ismutable(::Type{T}) where {T<:AbstractArray}
     if parent_type(T) <: T
         return true
@@ -168,12 +167,12 @@ function Base.setindex(x::AbstractMatrix, v, i::Int, j::Int)
 end
 
 """
-    can_setindex(x::DataType) -> Bool
+    can_setindex(::Type{T}) -> Bool
 
 Query whether a type can use `setindex!`.
 """
-can_setindex(x) = true
-can_setindex(x::AbstractArray) = can_setindex(typeof(x))
+can_setindex(x) = can_setindex(typeof(x))
+can_setindex(::Type) = true
 can_setindex(::Type{<:AbstractRange}) = false
 
 """
@@ -188,8 +187,8 @@ aos_to_soa(x) = x
 
 Query whether an array type has fast scalar indexing.
 """
-fast_scalar_indexing(x) = true
-fast_scalar_indexing(x::AbstractArray) = fast_scalar_indexing(typeof(x))
+fast_scalar_indexing(x) = fast_scalar_indexing(typeof(x))
+fast_scalar_indexing(::Type) = true
 fast_scalar_indexing(::Type{<:LinearAlgebra.AbstractQ}) = false
 fast_scalar_indexing(::Type{<:LinearAlgebra.LQPackedQ}) = false
 
@@ -208,34 +207,34 @@ A scalar `setindex!` which is always allowed.
 allowed_setindex!(x, v, i...) = Base.setindex!(x, v, i...)
 
 """
-    isstructured(x::DataType) -> Bool
+    isstructured(::Type{T}) -> Bool
 
 Query whether a type is a representation of a structured matrix.
 """
-isstructured(x) = false
-isstructured(x::AbstractArray) = isstructured(typeof(x))
-isstructured(::Symmetric) = true
-isstructured(::Hermitian) = true
-isstructured(::UpperTriangular) = true
-isstructured(::LowerTriangular) = true
-isstructured(::Tridiagonal) = true
-isstructured(::SymTridiagonal) = true
-isstructured(::Bidiagonal) = true
-isstructured(::Diagonal) = true
+isstructured(x) = isstructured(typeof(x))
+isstructured(::Type) = false
+isstructured(::Type{<:Symmetric}) = true
+isstructured(::Type{<:Hermitian}) = true
+isstructured(::Type{<:UpperTriangular}) = true
+isstructured(::Type{<:LowerTriangular}) = true
+isstructured(::Type{<:Tridiagonal}) = true
+isstructured(::Type{<:SymTridiagonal}) = true
+isstructured(::Type{<:Bidiagonal}) = true
+isstructured(::Type{<:Diagonal}) = true
 
 """
     has_sparsestruct(x::AbstractArray) -> Bool
 
 Determine whether `findstructralnz` accepts the parameter `x`.
 """
-has_sparsestruct(x) = false
-has_sparsestruct(x::AbstractArray) = has_sparsestruct(typeof(x))
-has_sparsestruct(x::Type{<:AbstractArray}) = false
-has_sparsestruct(x::Type{<:SparseMatrixCSC}) = true
-has_sparsestruct(x::Type{<:Diagonal}) = true
-has_sparsestruct(x::Type{<:Bidiagonal}) = true
-has_sparsestruct(x::Type{<:Tridiagonal}) = true
-has_sparsestruct(x::Type{<:SymTridiagonal}) = true
+has_sparsestruct(x) = has_sparsestruct(typeof(x))
+has_sparsestruct(::Type) = false
+has_sparsestruct(::Type{<:AbstractArray}) = false
+has_sparsestruct(::Type{<:SparseMatrixCSC}) = true
+has_sparsestruct(::Type{<:Diagonal}) = true
+has_sparsestruct(::Type{<:Bidiagonal}) = true
+has_sparsestruct(::Type{<:Tridiagonal}) = true
+has_sparsestruct(::Type{<:SymTridiagonal}) = true
 
 """
     issingular(A::AbstractMatrix) -> Bool

src/dimensions.jl

@@ -38,6 +38,7 @@ ndims_index(::Type{I}) where {N,I<:Tuple{Vararg{Any,N}}} = eachop(_ndims_index,
 
 """
     from_parent_dims(::Type{T}) -> Tuple{Vararg{Union{Int,StaticInt}}}
+    from_parent_dims(::Type{T}, dim) -> Union{Int,StaticInt}
 
 Returns the mapping from parent dimensions to child dimensions.
 """
@@ -71,11 +72,6 @@ function from_parent_dims(::Type{R}) where {T,N,S,A,R<:ReinterpretArray{T,N,S,A}
     end
 end
 
-"""
-    from_parent_dims(::Type{T}, dim) -> Union{Int,StaticInt}
-
-Returns the mapping from child dimensions to parent dimensions.
-"""
 from_parent_dims(x, dim) = from_parent_dims(typeof(x), dim)
 @aggressive_constprop function from_parent_dims(::Type{T}, dim::Int)::Int where {T}
     if dim > ndims(T)
@@ -99,6 +95,7 @@ end
 
 """
     to_parent_dims(::Type{T}) -> Tuple{Vararg{Union{Int,StaticInt}}}
+    to_parent_dims(::Type{T}, dim) -> Union{Int,StaticInt}
 
 Returns the mapping from child dimensions to parent dimensions.
 """
@@ -129,11 +126,6 @@ function to_parent_dims(::Type{R}) where {T,N,S,A,R<:ReinterpretArray{T,N,S,A}}
     end
 end
 
-"""
-    to_parent_dims(::Type{T}, dim) -> Union{Int,StaticInt}
-
-Returns the mapping from child dimensions to parent dimensions.
-"""
 to_parent_dims(x, dim) = to_parent_dims(typeof(x), dim)
 @aggressive_constprop function to_parent_dims(::Type{T}, dim::Int)::Int where {T}
     if dim > ndims(T)

src/ranges.jl

@@ -75,11 +75,10 @@ known_step(::Type{<:AbstractUnitRange{T}}) where {T} = one(T)
 """
     OptionallyStaticUnitRange(start, stop) <: AbstractUnitRange{Int}
 
-This range permits diverse representations of arrays to communicate common information
-about their indices. Each field may be an integer or `Val(<:Integer)` if it is known
-at compile time. An `OptionallyStaticUnitRange` is intended to be constructed internally
-from other valid indices. Therefore, users should not expect the same checks are used
-to ensure construction of a valid `OptionallyStaticUnitRange` as a `UnitRange`.
+Similar to `UnitRange` except each field may be an `Int` or `StaticInt`. An
+`OptionallyStaticUnitRange` is intended to be constructed internally from other valid
+indices. Therefore, users should not expect the same checks are used to ensure construction
+of a valid `OptionallyStaticUnitRange` as a `UnitRange`.
 """
 struct OptionallyStaticUnitRange{F<:CanonicalInt,L<:CanonicalInt} <: AbstractUnitRange{Int}
     start::F
@@ -140,13 +139,14 @@ the range operator (i.e., `:`).
 ```julia
 julia> using ArrayInterface
 
-julia> x = ArrayInterface.StaticInt(2);
+julia> x = ArrayInterface.static(2);
 
 julia> x:x:10
-ArrayInterface.StaticInt{2}():ArrayInterface.StaticInt{2}():10
+static(2):static(2):10
 
 julia> ArrayInterface.OptionallyStaticStepRange(x, x, 10)
-ArrayInterface.StaticInt{2}():ArrayInterface.StaticInt{2}():10
+static(2):static(2):10
+
 ```
 """
 struct OptionallyStaticStepRange{F<:CanonicalInt,S<:CanonicalInt,L<:CanonicalInt} <: OrdinalRange{Int,Int}
@@ -422,16 +422,16 @@ function Base.reverse(r::OptionallyStaticStepRange)
     return OptionallyStaticStepRange(static_last(r), -static_step(r), static_first(r))
 end
 
-function Base.show(io::IO, r::OptionallyStaticRange)
-    print(io, first(r))
+function Base.show(io::IO, ::MIME"text/plain", r::OptionallyStaticRange)
+    print(io, static_first(r))
     if known_step(r) === 1
         print(io, ":")
     else
         print(io, ":")
-        print(io, step(r))
+        print(io, static_step(r))
         print(io, ":")
     end
-    print(io, last(r))
+    print(io, static_last(r))
 end
 
 """
@@ -501,40 +501,40 @@ n = 16
 
 More importantly, `reduce_tup(_pick_range, inds)` often performs better than `reduce(_pick_range, inds)`.
 ```julia
-julia> using ArrayInterface, BenchmarkTools
+julia> using ArrayInterface, BenchmarkTools, Static
 
-julia> inds = (Base.OneTo(100), 1:100, 1:ArrayInterface.StaticInt(100))
-(Base.OneTo(100), 1:100, 1:Static(100))
+julia> inds = (Base.OneTo(100), 1:100, 1:static(100))
+(Base.OneTo(100), 1:100, 1:static(100))
 
 julia> @btime reduce(ArrayInterface._pick_range, \$(Ref(inds))[])
   6.405 ns (0 allocations: 0 bytes)
-Base.Slice(Static(1):Static(100))
+Base.Slice(static(1):static(100))
 
 julia> @btime ArrayInterface.reduce_tup(ArrayInterface._pick_range, \$(Ref(inds))[])
   2.570 ns (0 allocations: 0 bytes)
-Base.Slice(Static(1):Static(100))
+Base.Slice(static(1):static(100))
 
 julia> inds = (Base.OneTo(100), 1:100, 1:UInt(100))
 (Base.OneTo(100), 1:100, 0x0000000000000001:0x0000000000000064)
 
 julia> @btime reduce(ArrayInterface._pick_range, \$(Ref(inds))[])
   6.411 ns (0 allocations: 0 bytes)
-Base.Slice(Static(1):100)
+Base.Slice(static(1):100)
 
 julia> @btime ArrayInterface.reduce_tup(ArrayInterface._pick_range, \$(Ref(inds))[])
   2.592 ns (0 allocations: 0 bytes)
-Base.Slice(Static(1):100)
+Base.Slice(static(1):100)
 
 julia> inds = (Base.OneTo(100), 1:100, 1:UInt(100), Int32(1):Int32(100))
 (Base.OneTo(100), 1:100, 0x0000000000000001:0x0000000000000064, 1:100)
 
 julia> @btime reduce(ArrayInterface._pick_range, \$(Ref(inds))[])
   9.048 ns (0 allocations: 0 bytes)
-Base.Slice(Static(1):100)
+Base.Slice(static(1):100)
 
 julia> @btime ArrayInterface.reduce_tup(ArrayInterface._pick_range, \$(Ref(inds))[])
   2.569 ns (0 allocations: 0 bytes)
-Base.Slice(Static(1):100)
+Base.Slice(static(1):100)
 ```
 """
 @generated function reduce_tup(f::F, inds::Tuple{Vararg{Any,N}}) where {F,N}

src/size.jl

@@ -12,7 +12,7 @@ julia> using StaticArrays, ArrayInterface
 julia> A = @SMatrix rand(3,4);
 
 julia> ArrayInterface.size(A)
-(StaticInt{3}(), StaticInt{4}())
+(static(3), static(4))
 ```
 """
 function size(a::A) where {A}
@@ -22,7 +22,6 @@ function size(a::A) where {A}
         return size(parent(a))
     end
 end
-#size(a::AbstractVector) = (size(a, One()),)
 
 size(x::SubArray) = eachop(_sub_size, to_parent_dims(x), x.indices)
 _sub_size(x::Tuple, ::StaticInt{dim}) where {dim} = static_length(getfield(x, dim))

src/stridelayout.jl

@@ -66,7 +66,7 @@ function _offsets(x::X, dim::StaticInt{D}) where {X,D}
 end
 
 """
-    known_offset1(x) -> Union{Int,Nothing}
+    known_offset1(::Type{T}) -> Union{Int,Nothing}
 
 Returns the linear offset of array `x` if known at compile time.
 """
@@ -474,7 +474,8 @@ function known_strides(::Type{T}) where {T}
 end
 
 """
-    strides(A) -> Tuple
+    strides(A) -> Tuple{Vararg{Union{Int,StaticInt}}}
+    strides(A, dim) -> Union{Int,StaticInt}
 
 Returns the strides of array `A`. If any strides are known at compile time,
 these should be returned as `Static` numbers. For example: