More comprehensive documentation for #5428

- Include issue number in NEWS.md
- Added missing colons in error message
- More detailed explanation of balance options and what they do in the help text.

NEWS.md

@@ -108,7 +108,7 @@ Library improvements
 
   * `LinAlg` (linear algebra) improvements
 
-      * Balancing options for eigenvector calculations
+      * Balancing options for eigenvector calculations for general matrices ([#5428]).
 
     * Sparse linear algebra
 
@@ -206,6 +206,7 @@ Deprecated or removed
 [a448e080]: https://github.com/JuliaLang/julia/commit/a448e080dc736c7fb326426dfcb2528be36973d3
 [5e3f074b]: https://github.com/JuliaLang/julia/commit/5e3f074b9173044a0a4219f9b285879ff7cec041
 [#4967]: https://github.com/JuliaLang/julia/pull/4967
+[#5428]: https://github.com/JuliaLang/julia/pull/5428
 [#5468]: https://github.com/JuliaLang/julia/pull/5468
 
 Julia v0.2.0 Release Notes

base/linalg/factorization.jl

@@ -466,7 +466,7 @@ function eigfact!{T<:BlasComplex}(A::StridedMatrix{T}; balance::Symbol=:balance)
     n = size(A, 2)
     n == 0 && return Eigen(zeros(T, 0), zeros(T, 0, 0))
     ishermitian(A) && return eigfact!(Hermitian(A)) 
-    return Eigen(LAPACK.geevx!(balance == :balance ? 'B' : (balance == :diagonal ? 'S' : (balance == :permute ? 'P' : (balance == :nobalance ? 'N' : throw(ArgumentError("balance must be either ':balance', 'diagonal', 'permute' or 'nobalance'"))))), 'N', 'V', 'N', A)[[2,4]]...)
+    return Eigen(LAPACK.geevx!(balance == :balance ? 'B' : (balance == :diagonal ? 'S' : (balance == :permute ? 'P' : (balance == :nobalance ? 'N' : throw(ArgumentError("balance must be either ':balance', ':diagonal', ':permute' or ':nobalance'"))))), 'N', 'V', 'N', A)[[2,4]]...)
 end
 eigfact!(A::StridedMatrix; balance::Symbol=:balance) = eigfact!(float(A), balance=balance)
 eigfact{T<:BlasFloat}(x::StridedMatrix{T}; balance::Symbol=:balance) = eigfact!(copy(x), balance=balance)

doc/stdlib/linalg.rst

@@ -120,12 +120,16 @@ Linear algebra functions in Julia are largely implemented by calling functions f
 .. function:: eigvecs(A, [eigvals,][balance=:balance])
 
    Returns the eigenvectors of ``A``.
+   The ``balance`` keyword is the same as for :func:`eigfact`.
+
+   For ``SymTridiagonal`` matrices, if the optional vector of eigenvalues ``eigvals`` is specified, returns the specific corresponding eigenvectors.
 
-   For SymTridiagonal matrices, if the optional vector of eigenvalues ``eigvals`` is specified, returns the specific corresponding eigenvectors.
 
 .. function:: eigfact(A,[balance=:balance])
 
-   Compute the eigenvalue decomposition of ``A`` and return an ``Eigen`` object. If ``F`` is the factorization object, the eigenvalues can be accessed with ``F[:values]`` and the eigenvectors with ``F[:vectors]``. The following functions are available for ``Eigen`` objects: ``inv``, ``det``. For general non-symmetric matrices it is possible to specify how the matrix is balanced before the eigenvector calculation. Possible values are ``:balance``(default), ``:permute``,``:diagonal`` and ``:nobalance``.
+   Compute the eigenvalue decomposition of ``A`` and return an ``Eigen`` object. If ``F`` is the factorization object, the eigenvalues can be accessed with ``F[:values]`` and the eigenvectors with ``F[:vectors]``. The following functions are available for ``Eigen`` objects: ``inv``, ``det``.
+
+   For general non-symmetric matrices it is possible to specify how the matrix is balanced before the eigenvector calculation. Possible values are: ``:nobalance`` (do not balance), ``:permute`` (permute the matrix to become closer to upper triangular), ``:diagonal`` (scale the matrix by its diagonal elements to make rows and columns more equal in norm), and ``:balance`` (The default, i.e. both permute and scale the matrix).
 
 .. function:: eigfact(A, B)