document interface

Author: perazz

src/stdlib_linalg.fypp

@@ -223,6 +223,22 @@ module stdlib_linalg
 
   ! Least squares solution to system Ax=b, i.e. such that the 2-norm abs(b-Ax) is minimized.
   interface lstsq
+    !! version: experimental 
+    !!
+    !! Computes the squares solution to system \( A \cdot x = b \). 
+    !! ([Specification](../page/specs/stdlib_linalg.html#det-computes-the-determinant-of-a-square-matrix))
+    !! 
+    !!### Summary 
+    !! Interface for computing least squares, i.e. the 2-norm \( || (b-A \cdot x ||_2 \) minimizing solution.
+    !!
+    !!### Description
+    !! 
+    !! This interface provides methods for computing the least squares of a linear matrix system.
+    !! Supported data types include `real` and `complex`.
+    !! 
+    !!@note The solution is based on LAPACK's singular value decomposition `*GELSD` methods.
+    !!@note BLAS/LAPACK backends do not currently support extended precision (``xdp``).
+    !! 
     #:for nd,ndsuf,nde in ALL_RHS
     #:for rk,rt,ri in RC_KINDS_TYPES
     #:if rk!="xdp"

src/stdlib_linalg_least_squares.fypp

@@ -61,8 +61,24 @@ submodule (stdlib_linalg) stdlib_linalg_least_squares
      #:for rk,rt,ri in RC_KINDS_TYPES
      #:if rk!="xdp"
 
-     ! Compute the least-squares solution to a real system of linear equations Ax = B
+     ! Compute the least-squares solution to a real system of linear equations Ax = b
      module function stdlib_linalg_${ri}$_lstsq_${ndsuf}$(a,b,cond,overwrite_a,rank,err) result(x)
+     !!### Summary
+     !! Compute least-squares solution to a real system of linear equations \( Ax = b \) 
+     !!
+     !!### Description
+     !!
+     !! This function computes the least-squares solution of a linear matrix problem.
+     !!
+     !! param: a Input matrix of size [m,n].
+     !! param: b Right-hand-side vector of size [n] or matrix of size [n,nrhs].
+     !! param: cond [optional] Real input threshold indicating that singular values `s_i <= cond*maxval(s)` 
+     !!        do not contribute to the matrix rank.
+     !! param: overwrite_a [optional] Flag indicating if the input matrix can be overwritten.
+     !! param: rank [optional] integer flag returning matrix rank. 
+     !! param: err [optional] State return flag. 
+     !! return: x Solution vector of size [n] or solution matrix of size [n,nrhs].
+     !!
          !> Input matrix a[n,n]
          ${rt}$, intent(inout), target :: a(:,:)
          !> Right hand side vector or array, b[n] or b[n,nrhs]