Example:

The headers of an LAPACK routine DGESV, which performs Gaussian elimination on a general dense matrix, is listed in Table 1

 

      SUBROUTINE DGESV( N, NRHS, A, LDA, IPIV, B, LDB, INFO )
*
*     .. Scalar Arguments ..
      INTEGER            INFO, LDA, LDB, N, NRHS
*     ..
*     .. Array Arguments ..
      INTEGER            IPIV( * )
      DOUBLE PRECISION   A( LDA, * ), B( LDB, * )
*
*  Purpose
*  =======
*
*  DGESV computes the solution to a real system of linear equations A * X = B,
*  where A is an N-by-N matrix and X and B are N-by-NRHS matrices.
*
*  The LU decomposition with partial pivoting and row interchanges is
*  used to factor A as A = P * L * U,
*  where P is a permutation matrix, L is unit lower triangular, and U is
*  upper triangular.  The factored form of A is then used to solve the
*  system of equations A * X = B.
*
*  Arguments
*  =========
*
*  N       (input) INTEGER
*          The number of linear equations, i.e., the order of the
*          matrix A.  N >= 0.
*
*  NRHS    (input) INTEGER
*          The number of right hand sides, i.e., the number of columns
*          of the matrix B.  NRHS >= 0.
*
*  A       (input/output) DOUBLE PRECISION array, dimension (LDA,N)
*          On entry, the N-by-N coefficient matrix A.
*          On exit, the factors L and U from the factorization
*          A = P*L*U; the unit diagonal elements of L are not stored.
*
*  LDA     (input) INTEGER
*          The leading dimension of the array A.  LDA >= max(1,N).
*
*  IPIV    (output) INTEGER array, dimension (N)
*          The pivot indices that define the permutation matrix P;
*          row i of the matrix was interchanged with row IPIV(i).
*
*  B       (input/output) DOUBLE PRECISION array, dimension (LDB,NRHS)
*          On entry, the N-by-NRHS matrix of right hand side matrix B.
*          On exit, if INFO = 0, the N-by-NRHS solution matrix X.
*
*  LDB     (input) INTEGER
*          The leading dimension of the array B.  LDB >= max(1,N).
*
*  INFO    (output) INTEGER
*          = 0:  successful exit
*          < 0:  if INFO = -i, the i-th argument had an illegal value
*          > 0:  if INFO = i, U(i,i) is exactly zero.  The factorization
*                has been completed, but the factor U is exactly
*                singular, so the solution could not be computed.
*
*  =====================================================================
*
*     .. External Subroutines ..
      EXTERNAL           DGETRF, DGETRS, XERBLA
*     .. Intrinsic Functions ..
      INTRINSIC          MAX
*     .. Executable Statements ..

 
Table 1: LAPACK Subroutine DGESV -- LAPACK routine to perform a Gaussian Elimination on general full matrix.

Clearly LAPACK is well-documented. In fact, there is considerable duplication of information. If during development a subroutines interface were to change, then the routines documentation would have to be updated. In addition, the LAPACK HTML manual has a completely different (and more readable) style of documenting, which supplements the code documentation.

While this combination of documentation is extremely useful to software developers, the effort to produce it is enormous. Multiple passes over the code are needed to get the code documentation to exactly match a given subroutine's functionality. Furthermore the HTML and printed documentation are additional efforts. Such a documentation effort is only worthwhile, in our opinion, if a library is to attain a very high degree of distribution. For LAPACK this is certainly the case, but it will not be the case for PSAS.