Add doc strings and update old methods (#279)

* @assume_effects replaces @pure now

* Fix docs and outdated methods

More docs that got lost transitioning to libraries

* Fix typo in ArrayInterfaceOffsetArrays test

Author: Tokazama

Project.toml

@@ -1,6 +1,6 @@
 name = "ArrayInterface"
 uuid = "4fba245c-0d91-5ea0-9b3e-6abc04ee57a9"
-version = "6.0.3"
+version = "6.0.4"
 
 [deps]
 ArrayInterfaceCore = "30b0a656-2188-435a-8636-2ec0e6a096e2"

docs/src/api.md

@@ -26,7 +26,7 @@ ArrayInterfaceCore.findstructralnz
 ArrayInterfaceCore.lu_instance
 ArrayInterfaceCore.matrix_colors
 ArrayInterfaceCore.issingular
-ArrayInterfaceCoreCore.parent_type
+ArrayInterfaceCore.parent_type
 ArrayInterfaceCore.restructure
 ArrayInterfaceCore.safevec
 ArrayInterfaceCore.zeromatrix

lib/ArrayInterfaceCore/Project.toml

@@ -1,7 +1,7 @@
 name = "ArrayInterfaceCore"
 uuid = "30b0a656-2188-435a-8636-2ec0e6a096e2"
 authors = ["Zachary P. Christensen <zchristensen7@gmail.com>"]
-version = "0.1.3"
+version = "0.1.4"
 
 [deps]
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"

lib/ArrayInterfaceCore/src/ArrayInterfaceCore.jl

@@ -10,10 +10,15 @@ using SuiteSparse
 end
 _is_reshaped(::Type{<:Base.ReinterpretArray}) = false
 
-@generated function merge_tuple_type(::Type{X}, ::Type{Y}) where {X<:Tuple,Y<:Tuple}
-    Tuple{X.parameters...,Y.parameters...}
+@static if isdefined(Base, Symbol("@assume_effects"))
+    using Base: @constprop
+else
+    macro assume_effects(_, ex)
+        Base.@pure ex
+    end
 end
-Base.@pure __parameterless_type(T) = Base.typename(T).wrapper
+
+@assume_effects :total __parameterless_type(T) = Base.typename(T).wrapper
 parameterless_type(x) = parameterless_type(typeof(x))
 parameterless_type(x::Type) = __parameterless_type(x)
 

lib/ArrayInterfaceOffsetArrays/test/runtests.jl

@@ -27,5 +27,5 @@ o = OffsetArray(vec(A), 8);
 @test @inferred(ArrayInterface.device(OffsetArray(zeros(2,2,2),8,-2,-5))) === ArrayInterface.CPUPointer()
 
 offset_view = @view OffsetArrays.centered(zeros(eltype(A), 5, 5))[:, begin]; # SubArray of OffsetArray
-@test @inferred(ArrayInterface.known_offsets(out)) == (-2,)
+@test @inferred(ArrayInterface.known_offsets(offset_view)) == (-2,)
 

src/ArrayInterface.jl

@@ -4,7 +4,7 @@ using ArrayInterfaceCore
 import ArrayInterfaceCore: allowed_getindex, allowed_setindex!, aos_to_soa, buffer,
     parent_type, fast_matrix_colors, findstructralnz, has_sparsestruct,
     issingular, isstructured, matrix_colors, restructure, lu_instance,
-    safevec, zeromatrix, ColoringAlgorithm, merge_tuple_type,
+    safevec, zeromatrix, ColoringAlgorithm,
     fast_scalar_indexing, parameterless_type, _is_reshaped, ndims_index, is_splat_index
 
 # ArrayIndex subtypes and methods
@@ -34,6 +34,10 @@ using LinearAlgebra
 
 import Compat
 
+@generated function merge_tuple_type(::Type{X}, ::Type{Y}) where {X<:Tuple,Y<:Tuple}
+    Tuple{X.parameters...,Y.parameters...}
+end
+
 const CanonicalInt = Union{Int,StaticInt}
 canonicalize(x::Integer) = Int(x)
 canonicalize(@nospecialize(x::StaticInt)) = x

src/axes.jl

@@ -1,3 +1,10 @@
+
+"""
+    axes_types(::Type{T}) -> Type{Tuple{Vararg{AbstractUnitRange{Int}}}}
+    axes_types(::Type{T}, dim) -> Type{AbstractUnitRange{Int}}
+
+Returns the type of each axis for the `T`, or the type of of the axis along dimension `dim`.
+"""
 @inline axes_types(x, dim) = axes_types(x, to_dims(x, dim))
 @inline function axes_types(x, dim::StaticInt{D}) where {D}
     if D > ndims(x)
@@ -77,6 +84,17 @@ end
 # conditionally typed (but inferrable) axes. It also means we can't depend on constant
 # propagation to preserve statically sized axes. This should probably be addressed before
 # merging into Base Julia.
+"""
+    axes(A) -> Tuple{Vararg{AbstractUnitRange{Int}}}
+    axes(A, dim) -> AbstractUnitRange{Int}
+
+Returns the axis associated with each dimension of `A` or dimension `dim`.
+`ArrayInterface.axes(::AbstractArray)` behaves nearly identical to `Base.axes` with the
+exception of a handful of types replace `Base.OneTo{Int}` with `ArrayInterface.SOneTo`. For
+example, the axis along the first dimension of `Transpose{T,<:AbstractVector{T}}` and
+`Adjoint{T,<:AbstractVector{T}}` can be represented by `SOneTo(1)`. Similarly,
+`Base.ReinterpretArray`'s first axis may be statically sized.
+"""
 @inline axes(A) = Base.axes(A)
 axes(A::ReshapedArray) = Base.axes(A)
 axes(A::PermutedDimsArray) = permute(axes(parent(A)), to_parent_dims(A))
@@ -261,6 +279,20 @@ end
 
 Base.show(io::IO, x::LazyAxis{N}) where {N} = print(io, "LazyAxis{$N}($(parent(x))))")
 
+"""
+    lazy_axes(x)
+
+Produces a tuple of axes where each axis is constructed lazily. If an axis of `x` is already
+constructed or it is simply retrieved.
+"""
+@generated function lazy_axes(x::X) where {X}
+    Expr(:block, Expr(:meta, :inline), Expr(:tuple, [:(LazyAxis{$dim}(x)) for dim in 1:ndims(X)]...))
+end
+lazy_axes(x::LinearIndices) = axes(x)
+lazy_axes(x::CartesianIndices) = axes(x)
+@inline lazy_axes(x::MatAdjTrans) = reverse(lazy_axes(parent(x)))
+@inline lazy_axes(x::VecAdjTrans) = (SOneTo{1}(), first(lazy_axes(parent(x))))
+@inline lazy_axes(x::PermutedDimsArray) = permute(lazy_axes(parent(x)), to_parent_dims(x))
 @generated function lazy_axes(x::X) where {X}
     Expr(:block, Expr(:meta, :inline), Expr(:tuple, [:(LazyAxis{$dim}(x)) for dim in 1:ndims(X)]...))
 end

src/broadcast.jl

@@ -10,6 +10,21 @@ struct BroadcastAxisDefault <: BroadcastAxis end
 BroadcastAxis(x) = BroadcastAxis(typeof(x))
 BroadcastAxis(::Type{T}) where {T} = BroadcastAxisDefault()
 
+"""
+    broadcast_axis(x, y)
+
+Broadcast axis `x` and `y` into a common space. The resulting axis should be equal in length
+to both `x` and `y` unless one has a length of `1`, in which case the longest axis will be
+equal to the output.
+
+```julia
+julia> ArrayInterface.broadcast_axis(1:10, 1:10)
+
+julia> ArrayInterface.broadcast_axis(1:10, 1)
+1:10
+
+```
+"""
 broadcast_axis(x, y) = broadcast_axis(BroadcastAxis(x), x, y)
 # stagger default broadcasting in case y has something other than default
 broadcast_axis(::BroadcastAxisDefault, x, y) = _broadcast_axis(BroadcastAxis(y), x, y)