WIP: Update document of solveh.rs

Drop module-level doc in solveh.rs

lax/src/solveh.rs

@@ -1,13 +1,38 @@
-//! Solve symmetric linear problem using the Bunch-Kaufman diagonal pivoting method.
-//!
-//! See also [the manual of dsytrf](http://www.netlib.org/lapack/lapack-3.1.1/html/dsytrf.f.html)
-
 use crate::{error::*, layout::MatrixLayout, *};
 use cauchy::*;
 use num_traits::{ToPrimitive, Zero};
 
+#[cfg_attr(doc, katexit::katexit)]
+/// Solve symmetric/hermite indefinite linear problem using the [Bunch-Kaufman diagonal pivoting method][BK].
+///
+/// For a given symmetric matrix $A$,
+/// this method factorizes $A = U^T D U$ or $A = L D L^T$ where
+///
+/// - $U$ (or $L$) are is a product of permutation and unit upper (lower) triangular matrices
+/// - $D$ is symmetric and block diagonal with 1-by-1 and 2-by-2 diagonal blocks.
+///
+/// This takes two-step approach based in LAPACK:
+///
+/// 1. Factorize given matrix $A$ into upper ($U$) or lower ($L$) form with diagonal matrix $D$
+/// 2. Then solve linear equation $Ax = b$, and/or calculate inverse matrix $A^{-1}$
+///
+/// [BK]: https://doi.org/10.2307/2005787
+///
 pub trait Solveh_: Sized {
-    /// Bunch-Kaufman: wrapper of `*sytrf` and `*hetrf`
+    /// Factorize input matrix using Bunch-Kaufman diagonal pivoting method
+    ///
+    /// LAPACK correspondance
+    /// ----------------------
+    ///
+    /// | f32      | f64      | c32      | c64      |
+    /// |:---------|:---------|:---------|:---------|
+    /// | [ssytrf] | [dsytrf] | [chetrf] | [zhetrf] |
+    ///
+    /// [ssytrf]: https://netlib.org/lapack/explore-html/d0/d14/group__real_s_ycomputational_ga12d2e56511cf7df066712c61d9acec45.html
+    /// [dsytrf]: https://netlib.org/lapack/explore-html/d3/db6/group__double_s_ycomputational_gad91bde1212277b3e909eb6af7f64858a.html
+    /// [chetrf]: https://netlib.org/lapack/explore-html/d4/d74/group__complex_h_ecomputational_ga081dd1908e46d064c2bf0a1f6b664b86.html
+    /// [zhetrf]: https://netlib.org/lapack/explore-html/d3/d80/group__complex16_h_ecomputational_gadc84a5c9818ee12ea19944623131bd52.html
+    ///
     fn bk(l: MatrixLayout, uplo: UPLO, a: &mut [Self]) -> Result<Pivot>;
     /// Wrapper of `*sytri` and `*hetri`
     fn invh(l: MatrixLayout, uplo: UPLO, a: &mut [Self], ipiv: &Pivot) -> Result<()>;