Integrating Doxygen in comments

1 files changed, 268 insertions, 147 deletions

diff --git a/SRC/dlasd2.f b/SRC/dlasd2.f
index 7ff9066e..267cc2cb 100644
--- a/SRC/dlasd2.f
+++ b/SRC/dlasd2.f
@@ -1,3 +1,270 @@
+*> \brief \b DLASD2
+*
+*  =========== DOCUMENTATION ===========
+*
+* Online html documentation available at 
+*            http://www.netlib.org/lapack/explore-html/ 
+*
+*  Definition
+*  ==========
+*
+*       SUBROUTINE DLASD2( NL, NR, SQRE, K, D, Z, ALPHA, BETA, U, LDU, VT,
+*                          LDVT, DSIGMA, U2, LDU2, VT2, LDVT2, IDXP, IDX,
+*                          IDXC, IDXQ, COLTYP, INFO )
+* 
+*       .. Scalar Arguments ..
+*       INTEGER            INFO, K, LDU, LDU2, LDVT, LDVT2, NL, NR, SQRE
+*       DOUBLE PRECISION   ALPHA, BETA
+*       ..
+*       .. Array Arguments ..
+*       INTEGER            COLTYP( * ), IDX( * ), IDXC( * ), IDXP( * ),
+*      $                   IDXQ( * )
+*       DOUBLE PRECISION   D( * ), DSIGMA( * ), U( LDU, * ),
+*      $                   U2( LDU2, * ), VT( LDVT, * ), VT2( LDVT2, * ),
+*      $                   Z( * )
+*       ..
+*  
+*  Purpose
+*  =======
+*
+*>\details \b Purpose:
+*>\verbatim
+*>
+*> DLASD2 merges the two sets of singular values together into a single
+*> sorted set.  Then it tries to deflate the size of the problem.
+*> There are two ways in which deflation can occur:  when two or more
+*> singular values are close together or if there is a tiny entry in the
+*> Z vector.  For each such occurrence the order of the related secular
+*> equation problem is reduced by one.
+*>
+*> DLASD2 is called from DLASD1.
+*>
+*>\endverbatim
+*
+*  Arguments
+*  =========
+*
+*> \param[in] NL
+*> \verbatim
+*>          NL is INTEGER
+*>         The row dimension of the upper block.  NL >= 1.
+*> \endverbatim
+*>
+*> \param[in] NR
+*> \verbatim
+*>          NR is INTEGER
+*>         The row dimension of the lower block.  NR >= 1.
+*> \endverbatim
+*>
+*> \param[in] SQRE
+*> \verbatim
+*>          SQRE is INTEGER
+*>         = 0: the lower block is an NR-by-NR square matrix.
+*>         = 1: the lower block is an NR-by-(NR+1) rectangular matrix.
+*> \endverbatim
+*> \verbatim
+*>         The bidiagonal matrix has N = NL + NR + 1 rows and
+*>         M = N + SQRE >= N columns.
+*> \endverbatim
+*>
+*> \param[out] K
+*> \verbatim
+*>          K is INTEGER
+*>         Contains the dimension of the non-deflated matrix,
+*>         This is the order of the related secular equation. 1 <= K <=N.
+*> \endverbatim
+*>
+*> \param[in,out] D
+*> \verbatim
+*>          D is DOUBLE PRECISION array, dimension(N)
+*>         On entry D contains the singular values of the two submatrices
+*>         to be combined.  On exit D contains the trailing (N-K) updated
+*>         singular values (those which were deflated) sorted into
+*>         increasing order.
+*> \endverbatim
+*>
+*> \param[out] Z
+*> \verbatim
+*>          Z is DOUBLE PRECISION array, dimension(N)
+*>         On exit Z contains the updating row vector in the secular
+*>         equation.
+*> \endverbatim
+*>
+*> \param[in] ALPHA
+*> \verbatim
+*>          ALPHA is DOUBLE PRECISION
+*>         Contains the diagonal element associated with the added row.
+*> \endverbatim
+*>
+*> \param[in] BETA
+*> \verbatim
+*>          BETA is DOUBLE PRECISION
+*>         Contains the off-diagonal element associated with the added
+*>         row.
+*> \endverbatim
+*>
+*> \param[in,out] U
+*> \verbatim
+*>          U is DOUBLE PRECISION array, dimension(LDU,N)
+*>         On entry U contains the left singular vectors of two
+*>         submatrices in the two square blocks with corners at (1,1),
+*>         (NL, NL), and (NL+2, NL+2), (N,N).
+*>         On exit U contains the trailing (N-K) updated left singular
+*>         vectors (those which were deflated) in its last N-K columns.
+*> \endverbatim
+*>
+*> \param[in] LDU
+*> \verbatim
+*>          LDU is INTEGER
+*>         The leading dimension of the array U.  LDU >= N.
+*> \endverbatim
+*>
+*> \param[in,out] VT
+*> \verbatim
+*>          VT is DOUBLE PRECISION array, dimension(LDVT,M)
+*>         On entry VT**T contains the right singular vectors of two
+*>         submatrices in the two square blocks with corners at (1,1),
+*>         (NL+1, NL+1), and (NL+2, NL+2), (M,M).
+*>         On exit VT**T contains the trailing (N-K) updated right singular
+*>         vectors (those which were deflated) in its last N-K columns.
+*>         In case SQRE =1, the last row of VT spans the right null
+*>         space.
+*> \endverbatim
+*>
+*> \param[in] LDVT
+*> \verbatim
+*>          LDVT is INTEGER
+*>         The leading dimension of the array VT.  LDVT >= M.
+*> \endverbatim
+*>
+*> \param[out] DSIGMA
+*> \verbatim
+*>          DSIGMA is DOUBLE PRECISION array, dimension (N)
+*>         Contains a copy of the diagonal elements (K-1 singular values
+*>         and one zero) in the secular equation.
+*> \endverbatim
+*>
+*> \param[out] U2
+*> \verbatim
+*>          U2 is DOUBLE PRECISION array, dimension(LDU2,N)
+*>         Contains a copy of the first K-1 left singular vectors which
+*>         will be used by DLASD3 in a matrix multiply (DGEMM) to solve
+*>         for the new left singular vectors. U2 is arranged into four
+*>         blocks. The first block contains a column with 1 at NL+1 and
+*>         zero everywhere else; the second block contains non-zero
+*>         entries only at and above NL; the third contains non-zero
+*>         entries only below NL+1; and the fourth is dense.
+*> \endverbatim
+*>
+*> \param[in] LDU2
+*> \verbatim
+*>          LDU2 is INTEGER
+*>         The leading dimension of the array U2.  LDU2 >= N.
+*> \endverbatim
+*>
+*> \param[out] VT2
+*> \verbatim
+*>          VT2 is DOUBLE PRECISION array, dimension(LDVT2,N)
+*>         VT2**T contains a copy of the first K right singular vectors
+*>         which will be used by DLASD3 in a matrix multiply (DGEMM) to
+*>         solve for the new right singular vectors. VT2 is arranged into
+*>         three blocks. The first block contains a row that corresponds
+*>         to the special 0 diagonal element in SIGMA; the second block
+*>         contains non-zeros only at and before NL +1; the third block
+*>         contains non-zeros only at and after  NL +2.
+*> \endverbatim
+*>
+*> \param[in] LDVT2
+*> \verbatim
+*>          LDVT2 is INTEGER
+*>         The leading dimension of the array VT2.  LDVT2 >= M.
+*> \endverbatim
+*>
+*> \param[out] IDXP
+*> \verbatim
+*>          IDXP is INTEGER array dimension(N)
+*>         This will contain the permutation used to place deflated
+*>         values of D at the end of the array. On output IDXP(2:K)
+*>         points to the nondeflated D-values and IDXP(K+1:N)
+*>         points to the deflated singular values.
+*> \endverbatim
+*>
+*> \param[out] IDX
+*> \verbatim
+*>          IDX is INTEGER array dimension(N)
+*>         This will contain the permutation used to sort the contents of
+*>         D into ascending order.
+*> \endverbatim
+*>
+*> \param[out] IDXC
+*> \verbatim
+*>          IDXC is INTEGER array dimension(N)
+*>         This will contain the permutation used to arrange the columns
+*>         of the deflated U matrix into three groups:  the first group
+*>         contains non-zero entries only at and above NL, the second
+*>         contains non-zero entries only below NL+2, and the third is
+*>         dense.
+*> \endverbatim
+*>
+*> \param[in,out] IDXQ
+*> \verbatim
+*>          IDXQ is INTEGER array dimension(N)
+*>         This contains the permutation which separately sorts the two
+*>         sub-problems in D into ascending order.  Note that entries in
+*>         the first hlaf of this permutation must first be moved one
+*>         position backward; and entries in the second half
+*>         must first have NL+1 added to their values.
+*> \endverbatim
+*>
+*> \param[out] COLTYP
+*> \verbatim
+*>          COLTYP is INTEGER array dimension(N)
+*>         As workspace, this will contain a label which will indicate
+*>         which of the following types a column in the U2 matrix or a
+*>         row in the VT2 matrix is:
+*>         1 : non-zero in the upper half only
+*>         2 : non-zero in the lower half only
+*>         3 : dense
+*>         4 : deflated
+*> \endverbatim
+*> \verbatim
+*>         On exit, it is an array of dimension 4, with COLTYP(I) being
+*>         the dimension of the I-th type columns.
+*> \endverbatim
+*>
+*> \param[out] INFO
+*> \verbatim
+*>          INFO is INTEGER
+*>          = 0:  successful exit.
+*>          < 0:  if INFO = -i, the i-th argument had an illegal value.
+*> \endverbatim
+*>
+*
+*  Authors
+*  =======
+*
+*> \author Univ. of Tennessee 
+*> \author Univ. of California Berkeley 
+*> \author Univ. of Colorado Denver 
+*> \author NAG Ltd. 
+*
+*> \date November 2011
+*
+*> \ingroup auxOTHERauxiliary
+*
+*
+*  Further Details
+*  ===============
+*>\details \b Further \b Details
+*> \verbatim
+*>
+*>  Based on contributions by
+*>     Ming Gu and Huan Ren, Computer Science Division, University of
+*>     California at Berkeley, USA
+*>
+*> \endverbatim
+*>
+*  =====================================================================
       SUBROUTINE DLASD2( NL, NR, SQRE, K, D, Z, ALPHA, BETA, U, LDU, VT,
      $                   LDVT, DSIGMA, U2, LDU2, VT2, LDVT2, IDXP, IDX,
      $                   IDXC, IDXQ, COLTYP, INFO )
@@ -5,7 +272,7 @@
 *  -- LAPACK auxiliary routine (version 3.2) --
 *  -- LAPACK is a software package provided by Univ. of Tennessee,    --
 *  -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
-*     November 2006
+*     November 2011
 *
 *     .. Scalar Arguments ..
       INTEGER            INFO, K, LDU, LDU2, LDVT, LDVT2, NL, NR, SQRE
@@ -19,152 +286,6 @@
      $                   Z( * )
 *     ..
 *
-*  Purpose
-*  =======
-*
-*  DLASD2 merges the two sets of singular values together into a single
-*  sorted set.  Then it tries to deflate the size of the problem.
-*  There are two ways in which deflation can occur:  when two or more
-*  singular values are close together or if there is a tiny entry in the
-*  Z vector.  For each such occurrence the order of the related secular
-*  equation problem is reduced by one.
-*
-*  DLASD2 is called from DLASD1.
-*
-*  Arguments
-*  =========
-*
-*  NL     (input) INTEGER
-*         The row dimension of the upper block.  NL >= 1.
-*
-*  NR     (input) INTEGER
-*         The row dimension of the lower block.  NR >= 1.
-*
-*  SQRE   (input) INTEGER
-*         = 0: the lower block is an NR-by-NR square matrix.
-*         = 1: the lower block is an NR-by-(NR+1) rectangular matrix.
-*
-*         The bidiagonal matrix has N = NL + NR + 1 rows and
-*         M = N + SQRE >= N columns.
-*
-*  K      (output) INTEGER
-*         Contains the dimension of the non-deflated matrix,
-*         This is the order of the related secular equation. 1 <= K <=N.
-*
-*  D      (input/output) DOUBLE PRECISION array, dimension(N)
-*         On entry D contains the singular values of the two submatrices
-*         to be combined.  On exit D contains the trailing (N-K) updated
-*         singular values (those which were deflated) sorted into
-*         increasing order.
-*
-*  Z      (output) DOUBLE PRECISION array, dimension(N)
-*         On exit Z contains the updating row vector in the secular
-*         equation.
-*
-*  ALPHA  (input) DOUBLE PRECISION
-*         Contains the diagonal element associated with the added row.
-*
-*  BETA   (input) DOUBLE PRECISION
-*         Contains the off-diagonal element associated with the added
-*         row.
-*
-*  U      (input/output) DOUBLE PRECISION array, dimension(LDU,N)
-*         On entry U contains the left singular vectors of two
-*         submatrices in the two square blocks with corners at (1,1),
-*         (NL, NL), and (NL+2, NL+2), (N,N).
-*         On exit U contains the trailing (N-K) updated left singular
-*         vectors (those which were deflated) in its last N-K columns.
-*
-*  LDU    (input) INTEGER
-*         The leading dimension of the array U.  LDU >= N.
-*
-*  VT     (input/output) DOUBLE PRECISION array, dimension(LDVT,M)
-*         On entry VT**T contains the right singular vectors of two
-*         submatrices in the two square blocks with corners at (1,1),
-*         (NL+1, NL+1), and (NL+2, NL+2), (M,M).
-*         On exit VT**T contains the trailing (N-K) updated right singular
-*         vectors (those which were deflated) in its last N-K columns.
-*         In case SQRE =1, the last row of VT spans the right null
-*         space.
-*
-*  LDVT   (input) INTEGER
-*         The leading dimension of the array VT.  LDVT >= M.
-*
-*  DSIGMA (output) DOUBLE PRECISION array, dimension (N)
-*         Contains a copy of the diagonal elements (K-1 singular values
-*         and one zero) in the secular equation.
-*
-*  U2     (output) DOUBLE PRECISION array, dimension(LDU2,N)
-*         Contains a copy of the first K-1 left singular vectors which
-*         will be used by DLASD3 in a matrix multiply (DGEMM) to solve
-*         for the new left singular vectors. U2 is arranged into four
-*         blocks. The first block contains a column with 1 at NL+1 and
-*         zero everywhere else; the second block contains non-zero
-*         entries only at and above NL; the third contains non-zero
-*         entries only below NL+1; and the fourth is dense.
-*
-*  LDU2   (input) INTEGER
-*         The leading dimension of the array U2.  LDU2 >= N.
-*
-*  VT2    (output) DOUBLE PRECISION array, dimension(LDVT2,N)
-*         VT2**T contains a copy of the first K right singular vectors
-*         which will be used by DLASD3 in a matrix multiply (DGEMM) to
-*         solve for the new right singular vectors. VT2 is arranged into
-*         three blocks. The first block contains a row that corresponds
-*         to the special 0 diagonal element in SIGMA; the second block
-*         contains non-zeros only at and before NL +1; the third block
-*         contains non-zeros only at and after  NL +2.
-*
-*  LDVT2  (input) INTEGER
-*         The leading dimension of the array VT2.  LDVT2 >= M.
-*
-*  IDXP   (workspace) INTEGER array dimension(N)
-*         This will contain the permutation used to place deflated
-*         values of D at the end of the array. On output IDXP(2:K)
-*         points to the nondeflated D-values and IDXP(K+1:N)
-*         points to the deflated singular values.
-*
-*  IDX    (workspace) INTEGER array dimension(N)
-*         This will contain the permutation used to sort the contents of
-*         D into ascending order.
-*
-*  IDXC   (output) INTEGER array dimension(N)
-*         This will contain the permutation used to arrange the columns
-*         of the deflated U matrix into three groups:  the first group
-*         contains non-zero entries only at and above NL, the second
-*         contains non-zero entries only below NL+2, and the third is
-*         dense.
-*
-*  IDXQ   (input/output) INTEGER array dimension(N)
-*         This contains the permutation which separately sorts the two
-*         sub-problems in D into ascending order.  Note that entries in
-*         the first hlaf of this permutation must first be moved one
-*         position backward; and entries in the second half
-*         must first have NL+1 added to their values.
-*
-*  COLTYP (workspace/output) INTEGER array dimension(N)
-*         As workspace, this will contain a label which will indicate
-*         which of the following types a column in the U2 matrix or a
-*         row in the VT2 matrix is:
-*         1 : non-zero in the upper half only
-*         2 : non-zero in the lower half only
-*         3 : dense
-*         4 : deflated
-*
-*         On exit, it is an array of dimension 4, with COLTYP(I) being
-*         the dimension of the I-th type columns.
-*
-*  INFO   (output) INTEGER
-*          = 0:  successful exit.
-*          < 0:  if INFO = -i, the i-th argument had an illegal value.
-*
-*  Further Details
-*  ===============
-*
-*  Based on contributions by
-*     Ming Gu and Huan Ren, Computer Science Division, University of
-*     California at Berkeley, USA
-*
 *  =====================================================================
 *
 *     .. Parameters ..