More doctest examples for BLAS, some cleanup

Author: kshyatt

base/linalg/blas.jl

@@ -217,20 +217,41 @@ scal(n, DA, DX, incx) = scal!(n, DA, copy(DX), incx)
 
 Dot product of two vectors consisting of `n` elements of array `X` with stride `incx` and
 `n` elements of array `Y` with stride `incy`.
+
+# Example:
+```jldoctest
+julia> dot(10, ones(10), 1, ones(20), 2)
+10.0
+```
 """
 function dot end
 
 """
     dotc(n, X, incx, U, incy)
 
-Dot function for two complex vectors conjugating the first vector.
+Dot function for two complex vectors, consisting of `n` elements of array `X`
+with stride `incx` and `n` elements of array `U` with stride `incy`,
+conjugating the first vector.
+
+# Example:
+```jldoctest
+julia> Base.BLAS.dotc(10, im*ones(10), 1, complex(ones(20), ones(20)), 2)
+10.0 - 10.0im
+```
 """
 function dotc end
 
 """
     dotu(n, X, incx, Y, incy)
 
-Dot function for two complex vectors.
+Dot function for two complex vectors consisting of `n` elements of array `X`
+with stride `incx` and `n` elements of array `Y` with stride `incy`.
+
+# Example:
+```jldoctest
+julia> Base.BLAS.dotu(10, im*ones(10), 1, complex(ones(20), ones(20)), 2)
+-10.0 + 10.0im
+```
 """
 function dotu end
 
@@ -314,6 +335,15 @@ end
     nrm2(n, X, incx)
 
 2-norm of a vector consisting of `n` elements of array `X` with stride `incx`.
+
+# Example:
+```jldoctest
+julia> Base.BLAS.nrm2(4, ones(8), 2)
+2.0
+
+julia> Base.BLAS.nrm2(1, ones(8), 2)
+1.0
+```
 """
 function nrm2 end
 
@@ -339,6 +369,15 @@ nrm2(x::Array) = nrm2(length(x), pointer(x), 1)
     asum(n, X, incx)
 
 Sum of the absolute values of the first `n` elements of array `X` with stride `incx`.
+
+# Example:
+```jldoctest
+julia> Base.BLAS.asum(5, im*ones(10), 2)
+5.0
+
+julia> Base.BLAS.asum(2, im*ones(10), 5)
+2.0
+```
 """
 function asum end
 
@@ -363,7 +402,20 @@ asum(x::Array) = asum(length(x), pointer(x), 1)
 """
     axpy!(a, X, Y)
 
-Overwrite `Y` with `a*X + Y`. Returns `Y`.
+Overwrite `Y` with `a*X + Y`, where `a` is a scalar. Returns `Y`.
+
+# Example:
+```jldoctest
+julia> x = [1; 2; 3];
+
+julia> y = [4; 5; 6];
+
+julia> Base.BLAS.axpy!(2, x, y)
+3-element Array{Int64,1}:
+  6
+  9
+ 12
+```
 """
 function axpy! end
 
@@ -473,14 +525,15 @@ end
     gemv!(tA, alpha, A, x, beta, y)
 
 Update the vector `y` as `alpha*A*x + beta*y` or `alpha*A'x + beta*y` according to `tA`
-(transpose `A`). Returns the updated `y`.
+(transpose `A`). `alpha` and `beta` are scalars. Returns the updated `y`.
 """
 gemv!
 
 """
     gemv(tA, alpha, A, x)
 
 Returns `alpha*A*x` or `alpha*A'x` according to `tA` (transpose `A`).
+`alpha` is a scalar.
 """
 gemv(tA, alpha, A, x)
 
@@ -496,18 +549,18 @@ gemv(tA, A, x)
 """
     gbmv!(trans, m, kl, ku, alpha, A, x, beta, y)
 
-Update vector `y` as `alpha*A*x + beta*y` or `alpha*A'*x + beta*y` according to `trans` ('N'
-or 'T'). The matrix `A` is a general band matrix of dimension `m` by `size(A,2)` with `kl`
-sub-diagonals and `ku` super-diagonals. Returns the updated `y`.
+Update vector `y` as `alpha*A*x + beta*y` or `alpha*A'*x + beta*y` according to `trans` (`'N'` (meaning not transposed)
+or `'T'` (meaning transposed)). The matrix `A` is a general band matrix of dimension `m` by `size(A,2)` with `kl`
+sub-diagonals and `ku` super-diagonals. `alpha` and `beta` are scalars. Returns the updated `y`.
 """
 function gbmv! end
 
 """
     gbmv(trans, m, kl, ku, alpha, A, x, beta, y)
 
-Returns `alpha*A*x` or `alpha*A'*x` according to `trans` ('N' or 'T'). The matrix `A` is a
-general band matrix of dimension `m` by `size(A,2)` with `kl` sub-diagonals and `ku`
-super-diagonals.
+Returns `alpha*A*x` or `alpha*A'*x` according to `trans` (`'N'` (meaning not transposed) or `'T'` (meaning transposed)).
+The matrix `A` is a general band matrix of dimension `m` by `size(A,2)` with `kl` sub-diagonals and `ku`
+super-diagonals. `alpha` and `beta` are scalars.
 """
 function gbmv end
 
@@ -551,7 +604,7 @@ end
     symv!(ul, alpha, A, x, beta, y)
 
 Update the vector `y` as `alpha*A*x + beta*y`. `A` is assumed to be symmetric. Only the `ul`
-triangle of `A` is used. Returns the updated `y`.
+triangle of `A` is used. `alpha` and `beta` are scalars. Returns the updated `y`.
 """
 function symv! end
 
@@ -600,14 +653,17 @@ end
 """
     symv(ul, alpha, A, x)
 
-Returns `alpha*A*x`. `A` is assumed to be symmetric. Only the `ul` triangle of `A` is used.
+Returns `alpha*A*x`. `A` is assumed to be symmetric.
+Only the `ul` (`'U'` for upper, `'L'` for lower) triangle of `A` is used.
+`alpha` is a scalar.
 """
 symv(ul, alpha, A, x)
 
 """
     symv(ul, A, x)
 
-Returns `A*x`. `A` is assumed to be symmetric. Only the `ul` triangle of `A` is used.
+Returns `A*x`. `A` is assumed to be symmetric.
+Only the `ul` (`'U'` for upper, `'L'` for lower) triangle of `A` is used.
 """
 symv(ul, A, x)
 
@@ -683,6 +739,7 @@ end
 
 Returns `alpha*A*x` where `A` is a symmetric band matrix of order `size(A,2)` with `k`
 super-diagonals stored in the argument `A`.
+Only the `uplo` (`'U'` for upper, `'L'` for lower) triangle of `A` is used.
 """
 sbmv(uplo, k, alpha, A, x)
 
@@ -691,6 +748,7 @@ sbmv(uplo, k, alpha, A, x)
 
 Returns `A*x` where `A` is a symmetric band matrix of order `size(A,2)` with `k`
 super-diagonals stored in the argument `A`.
+Only the `uplo` (`'U'` for upper, `'L'` for lower) triangle of `A` is used.
 """
 sbmv(uplo, k, A, x)
 
@@ -701,6 +759,7 @@ Update vector `y` as `alpha*A*x + beta*y` where `A` is a a symmetric band matrix
 `size(A,2)` with `k` super-diagonals stored in the argument `A`. The storage layout for `A`
 is described the reference BLAS module, level-2 BLAS at
 <http://www.netlib.org/lapack/explore-html/>.
+Only the `uplo` (`'U'` for upper, `'L'` for lower) triangle of `A` is used.
 
 Returns the updated `y`.
 """
@@ -743,23 +802,26 @@ end
     trmv(ul, tA, dA, A, b)
 
 Returns `op(A)*b`, where `op` is determined by `tA`
-(`N` for identity, `T` for transpose `A`, and `C` for conjugate
-transpose `A`). Only the `ul` triangle (`U` for upper, `L`
-for lower) of `A` is used. `dA` indicates if `A` is
-unit-triangular (the diagonal is assumed to be all ones if `U`,
-or non-unit if `N`).
+(`'N'` for identity, `'T'` for transpose `A`, and `'C'` for conjugate
+transpose `A`). Only the `ul` triangle (`'U'` for upper, `'L'`
+for lower) of `A` is used.
+The diagonal is assumed to be all ones if `dA` is `'U'`, or the
+diagonal values are read from
+`A` if `dA` is `'N'`.
 """
 function trmv end
 
 """
     trmv!(ul, tA, dA, A, b)
 
 Returns `op(A)*b`, where `op` is determined by `tA`
-(`N` for identity, `T` for transpose `A`, and `C` for conjugate
-transpose `A`). Only the `ul` triangle (`U` for upper, `L`
-for lower) of `A` is used. `dA` indicates if `A` is
-unit-triangular (the diagonal is assumed to be all ones if `U`,
-or non-unit if `N`). The multiplication occurs in-place on `b`.
+(`'N'` for identity, `'T'` for transpose `A`, and `'C'` for conjugate
+transpose `A`). Only the `ul` triangle (`'U'` for upper, `'L'`
+for lower) of `A` is used.
+The diagonal is assumed to be all ones if `dA` is `'U'`, or the
+diagonal values are read from
+`A` if `dA` is `'N'`.
+The multiplication occurs in-place on `b`.
 """
 function trmv! end
 
@@ -798,8 +860,11 @@ end
     trsv!(ul, tA, dA, A, b)
 
 Overwrite `b` with the solution to `A*x = b` or one of the other two variants determined by
-`tA` (transpose `A`) and `ul` (triangle of `A` used). `dA` indicates if `A` is
-unit-triangular (the diagonal is assumed to be all ones). Returns the updated `b`.
+`tA` (transpose `A` if `'T'`, `A` if `'N'`, conjugate-transpose if `'C'`)
+and `ul` (triangle of `A` used, `'U'` for upper, `'L`' for lower).
+The diagonal is assumed to be all ones if `dA` is `'U'`, or the diagonal values are read from
+`A` if `dA` is `'N'`.
+Returns the updated `b`.
 """
 function trsv! end
 
@@ -808,7 +873,8 @@ function trsv! end
 
 Returns the solution to `A*x = b` or one of the other two variants determined by `tA`
 (transpose `A`) and `ul` (triangle of `A` is used.) `dA` indicates if `A` is unit-triangular
-(the diagonal is assumed to be all ones).
+(the diagonal is assumed to be all ones if `dA` is `'U'`, or the diagonal values are read from
+`A` if `dA` is `'N'`).
 """
 function trsv end
 
@@ -878,7 +944,7 @@ end
     syr!(uplo, alpha, x, A)
 
 Rank-1 update of the symmetric matrix `A` with vector `x` as `alpha*x*x.' + A`. When `uplo`
-is 'U' the upper triangle of `A` is updated ('L' for lower triangle). Returns `A`.
+is `'U'` the upper triangle of `A` is updated (`'L'` for lower triangle). Returns `A`.
 """
 function syr! end
 
@@ -908,7 +974,7 @@ end
     her!(uplo, alpha, x, A)
 
 Methods for complex arrays only. Rank-1 update of the Hermitian matrix `A` with vector `x`
-as `alpha*x*x' + A`. When `uplo` is 'U' the upper triangle of `A` is updated ('L' for lower
+as `alpha*x*x' + A`. When `uplo` is `'U'` the upper triangle of `A` is updated (`'L'` for lower
 triangle). Returns `A`.
 """
 function her! end
@@ -1045,15 +1111,15 @@ end
     symm(side, ul, alpha, A, B)
 
 Returns `alpha*A*B` or `alpha*B*A` according to `side`. `A` is assumed to be symmetric. Only
-the `ul` triangle of `A` is used.
+the `ul` triangle (`'U'` for upper, `'L'` for lower) of `A` is used.
 """
 symm(side, ul, alpha, A, B)
 
 """
     symm(side, ul, A, B)
 
 Returns `A*B` or `B*A` according to `side`. `A` is assumed to be symmetric. Only the `ul`
-triangle of `A` is used.
+triangle (`'U'` for upper, `'L'` for lower) of `A` is used.
 """
 symm(side, ul, A, B)
 
@@ -1068,7 +1134,8 @@ symm(tA::Char, tB::Char, alpha, A, B)
     symm!(side, ul, alpha, A, B, beta, C)
 
 Update `C` as `alpha*A*B + beta*C` or `alpha*B*A + beta*C` according to `side`. `A` is
-assumed to be symmetric. Only the `ul` triangle of `A` is used. Returns the updated `C`.
+assumed to be symmetric. Only the `ul` (`'U'` for upper, `'L'` for lower) triangle of
+`A` is used. Returns the updated `C`.
 """
 symm!
 
@@ -1116,16 +1183,16 @@ end
     syrk!(uplo, trans, alpha, A, beta, C)
 
 Rank-k update of the symmetric matrix `C` as `alpha*A*A.' + beta*C` or `alpha*A.'*A +
-beta*C` according to whether `trans` is 'N' or 'T'. When `uplo` is 'U' the upper triangle of
-`C` is updated ('L' for lower triangle). Returns `C`.
+beta*C` according to whether `trans` is `'N'` or `'T'`. When `uplo` is `'U'` the upper triangle of
+`C` is updated (`'L'` for lower triangle). Returns `C`.
 """
 function syrk! end
 
 """
     syrk(uplo, trans, alpha, A)
 
-Returns either the upper triangle or the lower triangle, according to `uplo` ('U' or 'L'),
-of `alpha*A*A.'` or `alpha*A.'*A`, according to `trans` ('N' or 'T').
+Returns either the upper triangle or the lower triangle, according to `uplo` (`'U'` or `'L'`),
+of `alpha*A*A.'` or `alpha*A.'*A`, according to `trans` (`'N'` or `'T'`).
 """
 function syrk end
 
@@ -1170,8 +1237,8 @@ syrk(uplo::Char, trans::Char, A::StridedVecOrMat) = syrk(uplo, trans, one(eltype
     herk!(uplo, trans, alpha, A, beta, C)
 
 Methods for complex arrays only. Rank-k update of the Hermitian matrix `C` as `alpha*A*A' +
-beta*C` or `alpha*A'*A + beta*C` according to whether `trans` is 'N' or 'T'. When `uplo` is
-'U' the upper triangle of `C` is updated ('L' for lower triangle). Returns `C`.
+beta*C` or `alpha*A'*A + beta*C` according to whether `trans` is `'N'` or `'T'`. When `uplo` is
+`'U'` the upper triangle of `C` is updated (`'L'` for lower triangle). Returns `C`.
 """
 function herk! end
 
@@ -1301,38 +1368,48 @@ end
 """
     trmm!(side, ul, tA, dA, alpha, A, B)
 
-Update `B` as `alpha*A*B` or one of the other three variants determined by `side` (`A` on
-left or right) and `tA` (transpose `A`). Only the `ul` triangle of `A` is used. `dA`
-indicates if `A` is unit-triangular (the diagonal is assumed to be all ones). Returns the
-updated `B`.
+Update `B` as `alpha*A*B` or one of the other three variants determined by `side` (`'L'` for `A` on
+left, `'R'` for `A` on right) and `tA` (transpose `A`). Only the `ul` (`'U'` for upper, `'L'` for lower)
+triangle of `A` is used.
+The diagonal is assumed to be all ones if `dA` is `'U'`, or the diagonal values are read from
+`A` if `dA` is `'N'`.
+Returns the updated `B`.
 """
 function trmm! end
 
 """
     trmm(side, ul, tA, dA, alpha, A, B)
 
-Returns `alpha*A*B` or one of the other three variants determined by `side` (`A` on left or
-right) and `tA` (transpose `A`). Only the `ul` triangle of `A` is used. `dA` indicates if
-`A` is unit-triangular (the diagonal is assumed to be all ones).
+Returns `alpha*A*B` or one of the other three variants determined by `side` (`'L'` for `A` on left,
+`'R'` for `A` on right) and `tA` (transpose `A`).
+Only the `ul` (`'U'` for upper, `'L'` for lower) triangle of `A` is used.
+The diagonal is assumed to be all ones if `dA` is `'U'`, or the diagonal values are read from
+`A` if `dA` is `'N'`.
 """
 function trmm end
 
 """
     trsm!(side, ul, tA, dA, alpha, A, B)
 
 Overwrite `B` with the solution to `A*X = alpha*B` or one of the other three variants
-determined by `side` (`A` on left or right of `X`) and `tA` (transpose `A`). Only the `ul`
-triangle of `A` is used. `dA` indicates if `A` is unit-triangular (the diagonal is assumed
-to be all ones). Returns the updated `B`.
+determined by `side` (`'L'` for `A` on left of `X`, `'R'` for `A` on right of `X`)
+and `tA` (transpose `A`).
+Only the `ul` (`'U'` for upper, `'L'` for lower) triangle of `A` is used.
+The diagonal is assumed to be all ones if `dA` is `'U'`, or the diagonal values are read from
+`A` if `dA` is `'N'`.
+Returns the updated `B`.
 """
 function trsm! end
 
 """
     trsm(side, ul, tA, dA, alpha, A, B)
 
 Returns the solution to `A*X = alpha*B` or one of the other three variants determined by
-`side` (`A` on left or right of `X`) and `tA` (transpose `A`). Only the `ul` triangle of `A`
-is used. `dA` indicates if `A` is unit-triangular (the diagonal is assumed to be all ones).
+determined by `side` (`'L'` for `A` on left of `X`, `'R'` for `A` on right of `X`)
+and `tA` (transpose `A`).
+Only the `ul` (`'U'` for upper, `'L'` for lower) triangle of `A` is used.
+The diagonal is assumed to be all ones if `dA` is `'U'`, or the diagonal values are read from
+`A` if `dA` is `'N'`.
 """
 function trsm end