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`. When `state` is not present, the corresponding `tridiagonal` call is `pure` and signals invalid sizes or array shape mismatches via an internal `error stop`. When `state` is present, the impure overload is used instead, and any such error is reported by setting the `state` variable rather than executing an `error 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 (`-`), the operand matrices `A` and `B` must be of the same type and kind and must have matching dimensions (`n`). The result `C` of the expression will then have the same dimensions as `A` (and `B`) when the operation is valid. 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