More docs (#49)

Author: andreasnoack

docs/Project.toml

@@ -1,5 +1,7 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Quaternions = "94ee1d12-ae83-5a48-8b1c-48b8ff168ae0"
 
 [compat]
 Documenter = "~0.21"

docs/src/index.md

@@ -8,4 +8,5 @@ CurrentModule = GenericLinearAlgebra
 
 ```@docs
 svd!
+svdvals!
 ```

src/svd.jl

@@ -425,7 +425,31 @@ function rmul!(A::AbstractMatrix, Q::LinearAlgebra.LQPackedQ)
 end
 
 # Overload LinearAlgebra methods
+
 LinearAlgebra.svdvals!(B::Bidiagonal{T}; tol = eps(T), debug = false) where T<:Real = _svdvals!(B, tol = tol, debug = debug)
+
+"""
+    svdvals!(A [, tol, debug])
+
+Generic computation of singular values.
+```jldoctest
+julia> using LinearAlgebra, GenericLinearAlgebra, Quaternions
+
+julia> n = 20;
+
+julia> H = [big(1)/(i + j - 1) for i in 1:n, j in 1:n]; # The Hilbert matrix
+
+julia> Float64(svdvals(H)[end]/svdvals(Float64.(H))[end] - 1) # The relative error of the LAPACK based solution in 64 bit floating point.
+-0.9999999999447275
+
+julia> A = qr([Quaternion(randn(4)...) for i in 1:3, j in 1:3]).Q *
+           Diagonal([3, 2, 1]) *
+           qr([Quaternion(randn(4)...) for i in 1:3, j in 1:3]).Q'; # A quaternion matrix with the singular value 1, 2, and 3.
+
+julia> svdvals(A) ≈ [3, 2, 1]
+true
+```
+"""
 function LinearAlgebra.svdvals!(A::StridedMatrix; tol = eps(real(eltype(A))), debug = false)
     B = bidiagonalize!(A).bidiagonal
     # It doesn't matter that we transpose the bidiagonal matrix when we are only interested in the values
@@ -436,9 +460,23 @@ end
 LinearAlgebra.svd!(B::Bidiagonal{T}; tol = eps(T), full = false, debug = false) where T<:Real = _svd!(B, tol = tol, debug = debug)
 
 """
-    svd!
+    svd!(A[, tol, full, debug])::SVD
+
+A generic singular value decomposition (SVD). The implementation only uses Julia functions so the SVD can be computed for any element type provided that the necessary arithmetic operations are supported by the element type.
+
+- `tol`: The relative tolerance for determining convergence. The default value is `eltype(T)` where `T` is the element type of the input matrix bidiagonal (i.e. after converting the matrix to bidiagonal form).
+
+- `full`: Sepcifies if all the left and right singular vectors be returned or if only the vectors us to the number of rows and columns of the input matrix `A` should be returned (the default).
+
+- `debug`: A Boolean flag to activate debug information during the executions of the algorithm. The default is false.
+
+# Algorithm
+...tomorrow
+
+# Example
 
-A generic SVD implementation.
+```jldoctest
+```
 """
 function LinearAlgebra.svd!(A::StridedMatrix{T}; tol = eps(real(eltype(A))), full = false, debug = false) where T