In-code documentation.

Author: loiseaujc

src/stdlib_specialmatrices.fypp

@@ -4,7 +4,10 @@
 #:set C_KINDS_TYPES = list(zip(CMPLX_KINDS, CMPLX_TYPES, CMPLX_SUFFIX))
 #:set KINDS_TYPES = R_KINDS_TYPES+C_KINDS_TYPES
 module stdlib_specialmatrices
-    use ieee_arithmetic
+    !! Provides derived-types and associated specialized linear algebra drivers
+    !! for highly-structured matrices commonly encountered in the discretization
+    !! of partial differential equations, as well as control and signal processing
+    !! applications. ([Specifications]](../page/specs/stdlib_specialmatrices.html))
     use stdlib_linalg_constants
     implicit none
     private
@@ -19,11 +22,10 @@ module stdlib_specialmatrices
     !-----                           ------
     !--------------------------------------
 
-    !! Version: experimental
-    !!
-    !! Tridiagonal matrix
+    !--> Tridiagonal matrices
     #:for k1, t1, s1 in (KINDS_TYPES)
     type, public :: Tridiagonal_${s1}$_type
+        !! Base type to define a `Tridiagonal` matrix.
         private
         ${t1}$, allocatable :: dl(:), dv(:), du(:)
         integer(ilp) :: n
@@ -37,9 +39,9 @@ module stdlib_specialmatrices
     !--------------------------------
 
     interface Tridiagonal
-        !! This interface provides different methods to construct a
-        !! `Tridiagonal` matrix. Only the non-zero elements of \( A \) are
-        !! stored, i.e.
+        !! ([Specifications](../page/specs/stdlib_specialmatrices.html#Tridiagonal)) This
+        !! interface provides different methods to construct a `Tridiagonal` matrix. Only
+        !! the non-zero elements of \( A \) are stored, i.e.
         !!
         !! \[
         !!    A
@@ -104,11 +106,13 @@ module stdlib_specialmatrices
     !-----                        -----
     !----------------------------------
 
-    !! Version: experimental
-    !!
-    !! Apply the matrix-vector product $$y = \alpha * op(M) * x + \beta * y $$
-    !! [Specifications](../page/specs/stdlib_specialmatrices.html#spmv)
     interface spmv
+        !! ([Specifications](../page/specs/stdlib_specialmatrices.html#spmv)) This
+        !! interface provides methods to compute the matrix-vector product
+        !!
+        !!  $$ y = \alpha \mathrm{op}(A) x + \beta y$$
+        !!
+        !! for the different matrix types defined by `stdlib_specialmatrices`.
         #:for k1, t1, s1 in (KINDS_TYPES)
         #:for rank in RANKS
         #:if k1 != "qp" and k1 != "xdp"
@@ -131,19 +135,10 @@ module stdlib_specialmatrices
     !-----                           -----
     !-------------------------------------
 
-    !! Version: experimental
-    !!
-    !! Convert a matrix of type `Tridiagonal` to its dense representation.
-    !! [Specifications](../page/specs/stdlib_specialmatrices.html#dense)
     interface dense
-        !! This interface provides methods to convert a `Tridiagonal` matrix
-        !! to a regular rank-2 array.
-        !!
-        !! #### Syntax
-        !!
-        !! ```fortran
-        !!    B = dense(A)
-        !! ```
+        !! This interface provides methods to convert a matrix of one of the
+        !! types defined by `stdlib_specialmatrices` to a standard rank-2 array.
+        !! ([Specifications](../page/specs/stdlib_specialmatrices.html#dense))
         #:for k1, t1, s1 in (KINDS_TYPES)
         pure module function tridiagonal_to_dense_${s1}$(A) result(B)
             !! Convert a `Tridiagonal` matrix to its dense representation.
@@ -155,11 +150,10 @@ module stdlib_specialmatrices
         #:endfor
     end interface
 
-    !! Version: experimental
-    !!
-    !! Returns the transpose of a `Tridiagonal` matrix.
-    !! [Specifications](../page/specs/stdlib_specialmatrices.html#transpose)
     interface transpose
+        !! This interface provides methods to compute the transpose operation for
+        !! the different matrix types defined by `stdlib_specialmatrices`.
+        !! [Specifications](../page/specs/stdlib_specialmatrices.html#transpose)
         #:for k1, t1, s1 in (KINDS_TYPES)
         pure module function transpose_tridiagonal_${s1}$(A) result(B)
             type(Tridiagonal_${s1}$_type), intent(in) :: A
@@ -169,11 +163,11 @@ module stdlib_specialmatrices
         #:endfor
     end interface
 
-    !! Version: experimental
-    !!
-    !! Returns the Hermitian of a `Tridiagonal` matrix.
-    !! [Specifications](../page/specs/stdlib_specialmatrices.html#hermitian)
     interface hermitian
+        !! This interface provides methods to compute the hermitian operation for
+        !! the different matrix types defined by `stdlib_specialmatrices`. For
+        !! real-valued matrices, this is equivalent to the standard `transpose`.
+        !! [Specifications](../page/specs/stdlib_specialmatrices.html#hermitian)
         #:for k1, t1, s1 in (KINDS_TYPES)
         pure module function hermitian_tridiagonal_${s1}$(A) result(B)
             type(Tridiagonal_${s1}$_type), intent(in) :: A
@@ -189,11 +183,10 @@ module stdlib_specialmatrices
     !-----                              -----
     !----------------------------------------
 
-    !! Version: experimental
-    !!
-    !! Overloads the scalar multiplication `*` for `Tridiagonal` matrices.
-    !! [Specifications](../page/specs/stdlib_specialmatrices.html#operator(*))
     interface operator(*)
+        !! Overload the `*` for scalar-matrix multiplications for the different matrix
+        !! types provided by `stdlib_specialmatrices`.
+        !! [Specifications](../page/specs/stdlib_specialmatrices.html#operators)
         #:for k1, t1, s1 in (KINDS_TYPES)
         pure module function scalar_multiplication_tridiagonal_${s1}$(alpha, A) result(B)
             ${t1}$, intent(in) :: alpha
@@ -208,11 +201,10 @@ module stdlib_specialmatrices
         #:endfor
     end interface
 
-    !! Version: experimental
-    !!
-    !! Overloads the addition `+` for `Tridiagonal` matrices.
-    !! [Specifications](../page/specs/stdlib_specialmatrices.html#operator(+))
     interface operator(+)
+        !! Overload the `+` operator for matrix-matrix addition. The two matrices need to
+        !! be of the same type and kind.
+        !! [Specifications](../page/specs/stdlib_specialmatrices.html#operators)
         #:for k1, t1, s1 in (KINDS_TYPES)
         pure module function matrix_add_tridiagonal_${s1}$(A, B) result(C)
             type(Tridiagonal_${s1}$_type), intent(in) :: A
@@ -222,11 +214,10 @@ module stdlib_specialmatrices
         #:endfor
     end interface
 
-    !! Version: experimental
-    !!
-    !! Overloads the subtraction `-` for `Tridiagonal` matrices.
-    !! [Specifications](../page/specs/stdlib_specialmatrices.html#operator(-))
     interface operator(-)
+        !! Overload the `-` operator for matrix-matrix subtraction. The two matrices need to
+        !! be of the same type and kind.
+        !! [Specifications](../page/specs/stdlib_specialmatrices.html#operators)
         #:for k1, t1, s1 in (KINDS_TYPES)
         pure module function matrix_sub_tridiagonal_${s1}$(A, B) result(C)
             type(Tridiagonal_${s1}$_type), intent(in) :: A