More documentation movement and cleanup for linalg (#18498)

* More documentation movement and cleanup for linalg

Removed square brackets from signatures, added
more links, clarified some wording.

* Fix docstring for bkfact

Author: kshyatt

base/docs/helpdb/Base.jl

@@ -2521,15 +2521,6 @@ Get the system time in seconds since the epoch, with fairly high (typically, mic
 """
 time()
 
-"""
-    qr(A [,pivot=Val{false}][;thin=true]) -> Q, R, [p]
-
-Compute the (pivoted) QR factorization of `A` such that either `A = Q*R` or `A[:,p] = Q*R`.
-Also see `qrfact`. The default is to compute a thin factorization. Note that `R` is not
-extended with zeros when the full `Q` is requested.
-"""
-qr
-
 """
     TextDisplay(stream)
 
@@ -2819,16 +2810,6 @@ retrieved by accessing `m.match` and the captured sequences can be retrieved by
 """
 match
 
-"""
-    qrfact!(A [,pivot=Val{false}])
-
-`qrfact!` is the same as [`qrfact`](:func:`qrfact`) when `A` is a subtype of
-`StridedMatrix`, but saves space by overwriting the input `A`, instead of creating a copy.
-An `InexactError` exception is thrown if the factorisation produces a number not
-representable by the element type of `A`, e.g. for integer types.
-"""
-qrfact!
-
 """
     coth(x)
 
@@ -3037,16 +3018,6 @@ offset `do`. Returns `dest`.
 """
 copy!(dest,d,src,so,N)
 
-"""
-    qrfact(A) -> SPQR.Factorization
-
-Compute the QR factorization of a sparse matrix `A`. A fill-reducing permutation is used.
-The main application of this type is to solve least squares problems with `\\`. The function
-calls the C library SPQR and a few additional functions from the library are wrapped but not
-exported.
-"""
-qrfact(A)
-
 """
     +(x, y...)
 
@@ -3085,19 +3056,6 @@ Reconstruct the matrix `A` from the factorization `F=factorize(A)`.
 """
 full(F)
 
-"""
-    full(QRCompactWYQ[, thin=true]) -> Matrix
-
-Converts an orthogonal or unitary matrix stored as a `QRCompactWYQ` object, i.e. in the
-compact WY format [^Bischof1987], to a dense matrix.
-
-Optionally takes a `thin` Boolean argument, which if `true` omits the columns that span the
-rows of `R` in the QR factorization that are zero. The resulting matrix is the `Q` in a thin
-QR factorization (sometimes called the reduced QR factorization). If `false`, returns a `Q`
-that spans all rows of `R` in its corresponding QR factorization.
-"""
-full(::LinAlg.QRCompactWYQ, ?)
-
 """
     throw(e)
 

base/linalg/bunchkaufman.jl

@@ -57,11 +57,11 @@ end
 """
     bkfact(A, uplo::Symbol=:U, symmetric::Bool=issymmetric(A), rook::Bool=false) -> BunchKaufman
 
-Compute the Bunch-Kaufman [^Bunch1977] factorization of a real symmetric or complex Hermitian
+Compute the Bunch-Kaufman [^Bunch1977] factorization of a symmetric or Hermitian
 matrix `A` and return a `BunchKaufman` object.
 `uplo` indicates which triangle of matrix `A` to reference.
 If `symmetric` is `true`, `A` is assumed to be symmetric. If `symmetric` is `false`,
-`A` is assumed to be complex Hermitian. If `rook` is `true`, rook pivoting is used. If
+`A` is assumed to be Hermitian. If `rook` is `true`, rook pivoting is used. If
 `rook` is false, rook pivoting is not used.
 The following functions are available for
 `BunchKaufman` objects: [`size`](:func:`size`), `\\`, [`inv`](:func:`inv`), [`issymmetric`](:func:`issymmetric`), [`ishermitian`](:func:`ishermitian`).

base/linalg/ldlt.jl

@@ -16,10 +16,9 @@ convert{T,S,U}(::Type{Factorization{T}}, F::LDLt{S,U}) = convert(LDLt{T,U}, F)
 
 # SymTridiagonal
 """
+    ldltfact!(S::SymTridiagonal) -> LDLt
 
-    ldltfact!(::SymTridiagonal) -> LDLt
-
-Same as `ldltfact`, but saves space by overwriting the input `A`, instead of creating a copy.
+Same as [`ldltfact`](:func:`ldltfact`), but saves space by overwriting the input `A`, instead of creating a copy.
 """
 function ldltfact!{T<:Real}(S::SymTridiagonal{T})
     n = size(S,1)
@@ -33,7 +32,7 @@ function ldltfact!{T<:Real}(S::SymTridiagonal{T})
 end
 
 """
-    ldltfact(::SymTridiagonal) -> LDLt
+    ldltfact(S::SymTridiagonal) -> LDLt
 
 Compute an `LDLt` factorization of a real symmetric tridiagonal matrix such that `A = L*Diagonal(d)*L'`
 where `L` is a unit lower triangular matrix and `d` is a vector. The main use of an `LDLt`

base/linalg/qr.jl

@@ -90,12 +90,21 @@ qrfact!{T<:BlasFloat}(A::StridedMatrix{T}, ::Type{Val{true}}) = QRPivoted(LAPACK
 qrfact!{T<:BlasFloat}(A::StridedMatrix{T}) = qrfact!(A, Val{false})
 
 # Generic fallbacks
+
+"""
+    qrfact!(A, pivot=Val{false})
+
+`qrfact!` is the same as [`qrfact`](:func:`qrfact`) when `A` is a subtype of
+`StridedMatrix`, but saves space by overwriting the input `A`, instead of creating a copy.
+An [`InexactError`](:obj:`InexactError`) exception is thrown if the factorisation produces a number not
+representable by the element type of `A`, e.g. for integer types.
+"""
 qrfact!(A::StridedMatrix, ::Type{Val{false}}) = qrfactUnblocked!(A)
 qrfact!(A::StridedMatrix, ::Type{Val{true}}) = qrfactPivotedUnblocked!(A)
 qrfact!(A::StridedMatrix) = qrfact!(A, Val{false})
 
 """
-    qrfact(A [,pivot=Val{false}]) -> F
+    qrfact(A, pivot=Val{false}) -> F
 
 Computes the QR factorization of `A`. The return type of `F` depends on the element type of
 `A` and whether pivoting is specified (with `pivot==Val{true}`).
@@ -117,9 +126,9 @@ The individual components of the factorization `F` can be accessed by indexing:
 | `F[:p]`   | pivot `Vector`                            |                 |                    | ✓               |
 | `F[:P]`   | (pivot) permutation `Matrix`              |                 |                    | ✓               |
 
-The following functions are available for the `QR` objects: `size`, `\\`. When `A` is
-rectangular, `\\` will return a least squares solution and if the solution is not unique,
-the one with smallest norm is returned.
+The following functions are available for the `QR` objects: [`size`](:func:`size`)
+and [`\\`](:func:`\\`). When `A` is rectangular, `\\` will return a least squares
+solution and if the solution is not unique, the one with smallest norm is returned.
 
 Multiplication with respect to either thin or full `Q` is allowed, i.e. both `F[:Q]*F[:R]`
 and `F[:Q]*A` are supported. A `Q` matrix can be converted into a regular matrix with
@@ -170,6 +179,14 @@ function qrfact{T}(A::AbstractMatrix{T})
 end
 qrfact(x::Number) = qrfact(fill(x,1,1))
 
+"""
+    qr(A, pivot=Val{false}; thin::Bool=true) -> Q, R, [p]
+
+Compute the (pivoted) QR factorization of `A` such that either `A = Q*R` or `A[:,p] = Q*R`.
+Also see [`qrfact`](:func:`qrfact`).
+The default is to compute a thin factorization. Note that `R` is not
+extended with zeros when the full `Q` is requested.
+"""
 qr(A::Union{Number, AbstractMatrix}, pivot::Union{Type{Val{false}}, Type{Val{true}}}=Val{false}; thin::Bool=true) =
     _qr(A, pivot, thin=thin)
 function _qr(A::Union{Number, AbstractMatrix}, ::Type{Val{false}}; thin::Bool=true)
@@ -182,22 +199,14 @@ function _qr(A::Union{Number, AbstractMatrix}, ::Type{Val{true}}; thin::Bool=tru
 end
 
 """
-    qr(v::AbstractVector)
+    qr(v::AbstractVector) -> w, r
 
 Computes the polar decomposition of a vector.
+Returns `w`, a unit vector in the direction of `v`, and
+`r`, the norm of `v`.
 
-Input:
-
-- `v::AbstractVector` - vector to normalize
-
-Outputs:
-
-- `w` - A unit vector in the direction of `v`
-- `r` - The norm of `v`
-
-See also:
-
-`normalize`, `normalize!`, `LinAlg.qr!`
+See also [`normalize`](:func:`normalize`), [`normalize!`](:func:`normalize!`),
+and [`LinAlg.qr!](:func:`LinAlg.qr!`).
 """
 function qr(v::AbstractVector)
     nrm = norm(v)
@@ -211,23 +220,15 @@ function qr(v::AbstractVector)
 end
 
 """
-    LinAlg.qr!(v::AbstractVector)
+    LinAlg.qr!(v::AbstractVector) -> w, r
 
 Computes the polar decomposition of a vector. Instead of returning a new vector
 as `qr(v::AbstractVector)`, this function mutates the input vector `v` in place.
+Returns `w`, a unit vector in the direction of `v` (this is a mutation of `v`),
+and `r`, the norm of `v`.
 
-Input:
-
-- `v::AbstractVector` - vector to normalize
-
-Outputs:
-
-- `w` - A unit vector in the direction of `v` (This is a mutation of `v`).
-- `r` - The norm of `v`
-
-See also:
-
-`normalize`, `normalize!`, `qr`
+See also [`normalize`](:func:`normalize`), [`normalize!`](:func:`normalize!`),
+and [`qr`](:func:`qr`).
 """
 function qr!(v::AbstractVector)
     nrm = norm(v)
@@ -317,6 +318,18 @@ convert{S}(::Type{QRCompactWYQ{S}}, Q::QRCompactWYQ) = QRCompactWYQ(convert(Abst
 convert{S}(::Type{AbstractMatrix{S}}, Q::QRCompactWYQ) = convert(QRCompactWYQ{S}, Q)
 convert{T}(::Type{Matrix}, A::Union{QRPackedQ{T},QRCompactWYQ{T}}) = A_mul_B!(A, eye(T, size(A.factors, 1), minimum(size(A.factors))))
 convert(::Type{Array}, A::Union{QRPackedQ,QRCompactWYQ}) = convert(Matrix, A)
+
+"""
+    full(A::Union{QRPackedQ,QRCompactWYQ}; thin::Bool=true) -> Matrix
+
+Converts an orthogonal or unitary matrix stored as a `QRCompactWYQ` object, i.e. in the
+compact WY format [^Bischof1987], or in the `QRPackedQ` format, to a dense matrix.
+
+Optionally takes a `thin` Boolean argument, which if `true` omits the columns that span the
+rows of `R` in the QR factorization that are zero. The resulting matrix is the `Q` in a thin
+QR factorization (sometimes called the reduced QR factorization). If `false`, returns a `Q`
+that spans all rows of `R` in its corresponding QR factorization.
+"""
 function full{T}(A::Union{QRPackedQ{T},QRCompactWYQ{T}}; thin::Bool = true)
     if thin
         convert(Array, A)

base/sparse/cholmod.jl

@@ -1264,6 +1264,8 @@ factorization `F`. `A` must be a `SparseMatrixCSC`, `Symmetric{SparseMatrixCSC}`
 or `Hermitian{SparseMatrixCSC}`. Note that even if `A` doesn't
 have the type tag, it must still be symmetric or Hermitian.
 
+See also [`cholfact`](:func:`cholfact`).
+
 !!! note
     This method uses the CHOLMOD library from SuiteSparse, which only supports
     doubles or complex doubles. Input matrices not of those element types will
@@ -1304,16 +1306,17 @@ Compute the Cholesky factorization of a sparse positive definite matrix `A`.
 have the type tag, it must still be symmetric or Hermitian.
 A fill-reducing permutation is used.
 `F = cholfact(A)` is most frequently used to solve systems of equations with `F\\b`,
-but also the methods `diag`, `det`, `logdet` are defined for `F`.
+but also the methods [`diag`](:func:`diag`), [`det`](:func:`det`), and
+[`logdet`](:func:`logdet`) are defined for `F`.
 You can also extract individual factors from `F`, using `F[:L]`.
 However, since pivoting is on by default, the factorization is internally
 represented as `A == P'*L*L'*P` with a permutation matrix `P`;
 using just `L` without accounting for `P` will give incorrect answers.
 To include the effects of permutation,
-it's typically preferable to extact "combined" factors like `PtL = F[:PtL]`
+it's typically preferable to extract "combined" factors like `PtL = F[:PtL]`
 (the equivalent of `P'*L`) and `LtP = F[:UP]` (the equivalent of `L'*P`).
 
-Setting optional `shift` keyword argument computes the factorization of
+Setting the optional `shift` keyword argument computes the factorization of
 `A+shift*I` instead of `A`. If the `perm` argument is nonempty,
 it should be a permutation of `1:size(A,1)` giving the ordering to use
 (instead of CHOLMOD's default AMD ordering).
@@ -1359,6 +1362,8 @@ Compute the ``LDL'`` factorization of `A`, reusing the symbolic factorization `F
 `Hermitian{SparseMatrixCSC}`. Note that even if `A` doesn't
 have the type tag, it must still be symmetric or Hermitian.
 
+See also [`ldltfact`](:func:`ldltfact`).
+
 !!! note
     This method uses the CHOLMOD library from SuiteSparse, which only supports
     doubles or complex doubles. Input matrices not of those element types will
@@ -1399,17 +1404,18 @@ Compute the ``LDL'`` factorization of a sparse matrix `A`.
 have the type tag, it must still be symmetric or Hermitian.
 A fill-reducing permutation is used. `F = ldltfact(A)` is most frequently
 used to solve systems of equations `A*x = b` with `F\\b`. The returned
-factorization object `F` also supports the methods `diag`,
-`det`, and `logdet`. You can extract individual factors from `F` using `F[:L]`.
+factorization object `F` also supports the methods [`diag`](:func:`diag`),
+[`det`](:func:`det`), and [`logdet`](:func:`logdet`).
+You can extract individual factors from `F` using `F[:L]`.
 However, since pivoting is on by default, the factorization is internally
 represented as `A == P'*L*D*L'*P` with a permutation matrix `P`;
 using just `L` without accounting for `P` will give incorrect answers.
-To include the effects of permutation, it is typically preferable to extact
+To include the effects of permutation, it is typically preferable to extract
 "combined" factors like `PtL = F[:PtL]` (the equivalent of
 `P'*L`) and `LtP = F[:UP]` (the equivalent of `L'*P`).
 The complete list of supported factors is `:L, :PtL, :D, :UP, :U, :LD, :DU, :PtLD, :DUP`.
 
-Setting optional `shift` keyword argument computes the factorization of
+Setting the optional `shift` keyword argument computes the factorization of
 `A+shift*I` instead of `A`. If the `perm` argument is nonempty,
 it should be a permutation of `1:size(A,1)` giving the ordering to use
 (instead of CHOLMOD's default AMD ordering).

base/sparse/spqr.jl

@@ -136,7 +136,17 @@ function qmult{Tv<:VTypes}(method::Integer, QR::Factorization{Tv}, X::Dense{Tv})
     d
 end
 
+
 qrfact(A::SparseMatrixCSC, ::Type{Val{true}}) = factorize(ORDERING_DEFAULT, DEFAULT_TOL, Sparse(A, 0))
+
+"""
+    qrfact(A) -> SPQR.Factorization
+
+Compute the `QR` factorization of a sparse matrix `A`. A fill-reducing permutation is used.
+The main application of this type is to solve least squares problems with `\\`. The function
+calls the C library SPQR and a few additional functions from the library are wrapped but not
+exported.
+"""
 qrfact(A::SparseMatrixCSC) = qrfact(A, Val{true})
 
 # With a real lhs and complex rhs with the same precision, we can reinterpret