doc: add missing docstrings to SparseArrays (#31286)

JuliaLang · Apr 3, 2019 · db428ef · db428ef
1 parent e0bef65
commit db428ef
Show file tree

Hide file tree

Showing 4 changed files with 36 additions and 0 deletions.
diff --git a/stdlib/SparseArrays/docs/src/index.md b/stdlib/SparseArrays/docs/src/index.md
@@ -202,6 +202,9 @@ section of the standard library reference.
 # [Sparse Arrays](@id stdlib-sparse-arrays)
 
 ```@docs
+SparseArrays.AbstractSparseArray
+SparseArrays.AbstractSparseVector
+SparseArrays.AbstractSparseMatrix
 SparseArrays.SparseVector
 SparseArrays.SparseMatrixCSC
 SparseArrays.sparse
@@ -217,6 +220,7 @@ SparseArrays.sprandn
 SparseArrays.nonzeros
 SparseArrays.rowvals
 SparseArrays.nzrange
+SparseArrays.droptol!
 SparseArrays.dropzeros!
 SparseArrays.dropzeros
 SparseArrays.permute

diff --git a/stdlib/SparseArrays/src/abstractsparse.jl b/stdlib/SparseArrays/src/abstractsparse.jl
@@ -1,8 +1,26 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
+"""
+    AbstractSparseArray{Tv,Ti,N}
 
+Supertype for `N`-dimensional sparse arrays (or array-like types) with elements
+of type `Tv` and index type `Ti`. [`SparseMatrixCSC`](@ref), [`SparseVector`](@ref)
+and `SuiteSparse.CHOLMOD.Sparse` are subtypes of this.
+"""
 abstract type AbstractSparseArray{Tv,Ti,N} <: AbstractArray{Tv,N} end
 
+"""
+    AbstractSparseVector{Tv,Ti}
+
+Supertype for one-dimensional sparse arrays (or array-like types) with elements
+of type `Tv` and index type `Ti`. Alias for `AbstractSparseArray{Tv,Ti,1}``.
+"""
 const AbstractSparseVector{Tv,Ti} = AbstractSparseArray{Tv,Ti,1}
+"""
+    AbstractSparseMatrix{Tv,Ti}
+
+Supertype for two-dimensional sparse arrays (or array-like types) with elements
+of type `Tv` and index type `Ti`. Alias for `AbstractSparseArray{Tv,Ti,2}`.
+"""
 const AbstractSparseMatrix{Tv,Ti} = AbstractSparseArray{Tv,Ti,2}
 
 """

diff --git a/stdlib/SparseArrays/src/sparsematrix.jl b/stdlib/SparseArrays/src/sparsematrix.jl
@@ -1232,6 +1232,13 @@ tril!(A::SparseMatrixCSC, k::Integer = 0, trim::Bool = true) =
 triu!(A::SparseMatrixCSC, k::Integer = 0, trim::Bool = true) =
     fkeep!(A, (i, j, x) -> j >= i + k, trim)
 
+"""
+    droptol!(A::SparseMatrixCSC, tol; trim::Bool = true)
+
+Removes stored values from `A` whose absolute value is (strictly) larger than `tol`,
+optionally trimming resulting excess space from `A.rowval` and `A.nzval` when `trim`
+is `true`.
+"""
 droptol!(A::SparseMatrixCSC, tol; trim::Bool = true) =
     fkeep!(A, (i, j, x) -> abs(x) > tol, trim)
 

diff --git a/stdlib/SparseArrays/src/sparsevector.jl b/stdlib/SparseArrays/src/sparsevector.jl
@@ -1911,6 +1911,13 @@ function fkeep!(x::SparseVector, f, trim::Bool = true)
     x
 end
 
+"""
+    droptol!(x::SparseVector, tol; trim::Bool = true)
+
+Removes stored values from `x` whose absolute value is (strictly) larger than `tol`,
+optionally trimming resulting excess space from `A.rowval` and `A.nzval` when `trim`
+is `true`.
+"""
 droptol!(x::SparseVector, tol; trim::Bool = true) = fkeep!(x, (i, x) -> abs(x) > tol, trim)
 
 """