add state argument and dimension constraints to specialmatrices…

doc/specs/stdlib_specialmatrices.md

@@ -64,11 +64,13 @@ Tridiagonal matrices are available with all supported data types as `tridiagonal
 
 - To construct a tridiagonal matrix from already allocated arrays `dl` (lower diagonal, size `n-1`), `dv` (main diagonal, size `n`) and `du` (upper diagonal, size `n-1`):
 
-`A = ` [[stdlib_specialmatrices(module):tridiagonal(interface)]] `(dl, dv, du)`
+`A = ` [[stdlib_specialmatrices(module):tridiagonal(interface)]] `(dl, dv, du [, state])`
 
 - To construct a tridiagonal matrix of size `n x n` with constant diagonal elements `dl`, `dv`, and `du`:
 
-`A = ` [[stdlib_specialmatrices(module):tridiagonal(interface)]] `(dl, dv, du, n)`
+`A = ` [[stdlib_specialmatrices(module):tridiagonal(interface)]] `(dl, dv, du, n [, state])`
+
+Where `state` is an optional `intent(out)` argument of type `linalg_state_type`. If provided, it will catch and store error states (such as invalid sizes or array shape mismatches) instead of triggering a hard program stop.
 
 #### Example
 
@@ -207,5 +209,5 @@ The definition of all standard artihmetic operators have been overloaded to be a
 `B = alpha` [[stdlib_specialmatrices(module):operator(*)(interface)]] `A`
 
 @note
-For addition (`+`) and subtraction (`-`), matrices `A`, `B` and `C` all need to be of the same type and kind. For scalar multiplication (`*`), `A` and `B` need to be of the same type and kind, while `alpha` is either `real` or `complex` (with the same kind again) depending on the type being used.
+For addition (`+`) and subtraction (`-`), matrices `A`, `B` and `C` all need to be of the same type, kind, and must have matching dimensions (`n`). For scalar multiplication (`*`), `A` and `B` need to be of the same type and kind, while `alpha` is either `real` or `complex` (with the same kind again) depending on the type being used.
 @endnote