Skip to content

Update examples and signatures in docstrings #506

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
abhro wants to merge 2 commits into
base: master
Choose a base branch
from
+33 −37
Open

Update examples and signatures in docstrings #506

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2e64a54
Update examples and signatures in docstrings
abhro Aug 30, 2026
9ec9164
Ignore docs/build/ from repository tracking
abhro Aug 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,6 @@
*.jl.*.cov
*.jl.mem
deps/deps.jl
docs/build
Manifest.toml
*~
69 changes: 32 additions & 37 deletions src/ArrayInterface.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Returns tuple where each field corresponds to the field type of `T` modified by

# Examples

```julia
```julia-repl
julia> ArrayInterface.map_tuple_type(sqrt, Tuple{1,4,16})
(1.0, 2.0, 4.0)

Expand All @@ -37,7 +37,7 @@ Flattens any field of `t` that is a tuple. Only direct fields of `t` may be flat

# Examples

```julia
```julia-repl
julia> ArrayInterface.flatten_tuples((1, ()))
(1,)

Expand Down Expand Up @@ -138,15 +138,13 @@ See also [`SetIndex!`](@ref)

# Examples

```julia
```julia-repl
julia> ArrayInterface.GetIndex(1:10)(3)
3

julia> ArrayInterface.GetIndex{false}(1:10)(11) # shouldn't be in-bounds
11

```

"""
struct GetIndex{CB, B} <: Function
buffer::B
Expand Down Expand Up @@ -175,15 +173,13 @@ See also [`GetIndex`](@ref)

# Examples

```julia

```julia-repl
julia> x = [1, 2, 3, 4];

julia> ArrayInterface.SetIndex!(x)(10, 2);

julia> x[2]
10

```
"""
struct SetIndex!{CB, B} <: Function
Expand Down Expand Up @@ -224,7 +220,7 @@ function ismutable end
ismutable(::Type{T}) -> Bool

Query whether instances of type `T` are mutable or not, see
https://github.com/JuliaDiffEq/RecursiveArrayTools.jl/issues/19.
<https://github.com/JuliaDiffEq/RecursiveArrayTools.jl/issues/19>.
"""
ismutable(x) = ismutable(typeof(x))
function ismutable(::Type{T}) where {T <: AbstractArray}
Expand Down Expand Up @@ -319,7 +315,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)
Expand Down Expand Up @@ -416,7 +412,7 @@ matrix_colors(A::Union{Tridiagonal, SymTridiagonal}) = _cycle(1:3, Base.size(A,
_cycle(repetend, len) = repeat(repetend, div(len, length(repetend)) + 1)[1:len]

"""
bunchkaufman_instance(A, pivot = LinearAlgebra.RowMaximum()) -> bunchkaufman_factorization_instance
bunchkaufman_instance(A, pivot = LinearAlgebra.RowMaximum()) -> bunchkaufman_factorization_instance

Returns an instance of the Bunch-Kaufman factorization object with the correct type
cheaply.
Expand All @@ -426,14 +422,14 @@ function bunchkaufman_instance(A::Matrix{T}) where T
end

"""
bunchkaufman_instance(a::Number) -> a
bunchkaufman_instance(a::Number) -> a

Returns the number.
"""
bunchkaufman_instance(a::Number) = a

"""
bunchkaufman_instance(a::Any) -> cholesky(a, check=false)
bunchkaufman_instance(a::Any) -> cholesky(a, check=false)

Returns the number.
"""
Expand All @@ -442,7 +438,7 @@ bunchkaufman_instance(a::Any) = bunchkaufman(a, check = false)
const DEFAULT_CHOLESKY_PIVOT = LinearAlgebra.NoPivot()

"""
cholesky_instance(A, pivot = LinearAlgebra.NoPivot()) -> cholesky_factorization_instance
cholesky_instance(A, pivot = LinearAlgebra.NoPivot()) -> cholesky_factorization_instance

Returns an instance of the Cholesky factorization object with the correct type
cheaply.
Expand All @@ -452,22 +448,22 @@ function cholesky_instance(A::Matrix{T}, pivot = DEFAULT_CHOLESKY_PIVOT) where {
end

"""
cholesky_instance(a::Number, pivot = LinearAlgebra.NoPivot()) -> a
cholesky_instance(a::Number, pivot = LinearAlgebra.NoPivot()) -> a

Returns the number.
"""
cholesky_instance(a::Number, pivot = DEFAULT_CHOLESKY_PIVOT) = a

"""
cholesky_instance(a::Any, pivot = LinearAlgebra.NoPivot()) -> cholesky(a, check=false)
cholesky_instance(a::Any, pivot = LinearAlgebra.NoPivot()) -> cholesky(a, check=false)

Slow fallback which gets the instance via factorization. Should get
specialized for new matrix types.
"""
cholesky_instance(a::Any, pivot = DEFAULT_CHOLESKY_PIVOT) = cholesky(a, pivot, check = false)

"""
ldlt_instance(A) -> ldlt_factorization_instance
ldlt_instance(A) -> ldlt_factorization_instance

Returns an instance of the LDLT factorization object with the correct type
cheaply.
Expand All @@ -481,22 +477,22 @@ function ldlt_instance(A::SymTridiagonal{T,V}) where {T,V}
end

"""
ldlt_instance(a::Number) -> a
ldlt_instance(a::Number) -> a

Returns the number.
"""
ldlt_instance(a::Number) = a

"""
ldlt_instance(a::Any) -> ldlt(a, check=false)
ldlt_instance(a::Any) -> ldlt(a, check=false)

Slow fallback which gets the instance via factorization. Should get
specialized for new matrix types.
"""
ldlt_instance(a::Any) = ldlt(a)

"""
lu_instance(A) -> lu_factorization_instance
lu_instance(A) -> lu_factorization_instance

Returns an instance of the LU factorization object with the correct type
cheaply.
Expand Down Expand Up @@ -532,22 +528,22 @@ function lu_instance(A::Union{Tridiagonal{T},Diagonal{T},SymTridiagonal{T}}) whe
end

"""
lu_instance(a::Number) -> a
lu_instance(a::Number) -> a

Returns the number.
"""
lu_instance(a::Number) = a

"""
lu_instance(a::Any) -> lu(a, check=false)
lu_instance(a::Any) -> lu(a, check = false)

Slow fallback which gets the instance via factorization. Should get
specialized for new matrix types.
"""
lu_instance(a::Any) = lu(a, check = false)

"""
qr_instance(A, pivot = NoPivot()) -> qr_factorization_instance
qr_instance(A, pivot = NoPivot()) -> qr_factorization_instance

Returns an instance of the QR factorization object with the correct type
cheaply.
Expand All @@ -565,7 +561,7 @@ function qr_instance(A::Matrix{BigFloat},pivot = DEFAULT_CHOLESKY_PIVOT)
end

"""
qr_instance(a::Number) -> a
qr_instance(a::Number) -> a

Returns the number.
"""
Expand All @@ -580,7 +576,7 @@ specialized for new matrix types.
qr_instance(a::Any, pivot = DEFAULT_CHOLESKY_PIVOT) = qr(a)# check = false)

"""
svd_instance(A) -> qr_factorization_instance
svd_instance(A) -> qr_factorization_instance

Returns an instance of the SVD factorization object with the correct type
cheaply.
Expand All @@ -590,7 +586,7 @@ function svd_instance(A::Matrix{T}) where {T}
end

"""
svd_instance(a::Number) -> a
svd_instance(a::Number) -> a

Returns the number.
"""
Expand Down Expand Up @@ -747,14 +743,14 @@ fast_scalar_indexing(::Type{<:LinearAlgebra.AbstractQ}) = false
fast_scalar_indexing(::Type{<:LinearAlgebra.LQPackedQ}) = false

"""
allowed_getindex(x,i...)
allowed_getindex(x, i...)

A scalar `getindex` which is always allowed.
"""
allowed_getindex(x, i...) = x[i...]

"""
allowed_setindex!(x,v,i...)
allowed_setindex!(x, v, i...)

A scalar `setindex!` which is always allowed.
"""
Expand Down Expand Up @@ -828,7 +824,7 @@ See also [`ndims_shape`](@ref)

# Examples

```julia
```julia-repl
julia> ArrayInterface.ndims_index(Int)
1

Expand Down Expand Up @@ -859,13 +855,13 @@ See also [`ndims_index`](@ref)

# Examples

```julia
```julia-repl
julia> ArrayInterface.ndims_shape([CartesianIndex(1, 1), CartesianIndex(1, 2)])
1

julia> ndims(CartesianIndices((2,2))[[CartesianIndex(1, 1), CartesianIndex(1, 2)]])
1

```
"""
ndims_shape(T::DataType) = ndims_index(T)
ndims_shape(::Type{Colon}) = 1
Expand All @@ -876,7 +872,6 @@ ndims_shape(@nospecialize T::Type{<:AbstractArray}) = ndims(T)
ndims_shape(x) = ndims_shape(typeof(x))



"""
instances_do_not_alias(::Type{T}) -> Bool

Expand Down Expand Up @@ -920,7 +915,7 @@ end
"""
defines_strides(::Type{T}) -> Bool

Is strides(::T) defined? It is assumed that types returning `true` also return a valid
Is `strides(::T)` defined? It is assumed that types returning `true` also return a valid
pointer on `pointer(::T)`.
"""
defines_strides(x) = defines_strides(typeof(x))
Expand Down Expand Up @@ -965,7 +960,7 @@ interface.

# Examples

```julia
```julia-repl
julia> ArrayInterface.ensures_all_unique(BitSet())
true

Expand Down Expand Up @@ -994,7 +989,7 @@ Returns `true` if all instances of `T` are sorted.

# Examples

```julia
```julia-repl
julia> ArrayInterface.ensures_sorted(BitSet())
true

Expand All @@ -1019,8 +1014,8 @@ Note: This checks if a compatible `convert` methood exists between `T` and `args

# Examples:

```julia
julia> ca = ComponentVector((x = rand(3), y = rand(4),))
```julia-repl
julia> ca = ComponentVector((x = rand(3), y = rand(4)))
ComponentVector{Float64}(x = [0.6549137106381634, 0.37555505280294565, 0.8521039568665254], y = [0.40314196291239024, 0.35484725607638834, 0.6580528978034597, 0.10055508457632167])

julia> ArrayInterface.has_trivial_array_constructor(typeof(ca), ones(6))
Expand Down