Additional documentation (#158)

Additional documentation

src/algebra/csc/core.rs

@@ -51,7 +51,7 @@ pub struct CscMatrix<T = f64> {
     pub n: usize,
     /// CSC format column pointer.   
     ///
-    /// Ths field should have length `n+1`. The last entry corresponds
+    /// This field should have length `n+1`. The last entry corresponds
     /// to the the number of nonzeros and should agree with the lengths
     /// of the `rowval` and `nzval` fields.
     pub colptr: Vec<usize>,
@@ -419,7 +419,7 @@ where
         self.size() == other.size() && self.colptr == other.colptr && self.rowval == other.rowval
     }
 
-    /// Same as is_equal_sparsity, but returns an error indicating the reason
+    /// Same as `is_equal_sparsity`, but returns an error indicating the reason
     /// for failure if the matrices do not have equivalent sparsity patterns.
     pub fn check_equal_sparsity(&self, other: &Self) -> Result<(), SparseFormatError> {
         if self.size() != other.size() {

src/algebra/dense/types.rs

@@ -10,7 +10,7 @@ where
 {
     /// dimensions
     pub size: (usize, usize),
-    /// vector of data in column major formmat
+    /// vector of data in column major format
     pub data: S,
     pub(crate) phantom: std::marker::PhantomData<T>,
 }

src/algebra/error_types.rs

@@ -4,21 +4,27 @@ use thiserror::Error;
 #[derive(Error, Debug)]
 pub enum MatrixConcatenationError {
     #[error("Incompatible dimensions")]
+    /// Indicates inputs have incompatible dimension
     IncompatibleDimension,
 }
 
 #[derive(Error, Debug)]
 /// Error type returned by sparse matrix assembly operations.
 pub enum SparseFormatError {
+    /// Matrix dimension fields and/or array lengths are incompatible
     #[error("Matrix dimension fields and/or array lengths are incompatible")]
     IncompatibleDimension,
+    /// Data is not sorted by row index within each column
     #[error("Data is not sorted by row index within each column")]
     BadRowOrdering,
     #[error("Row value exceeds the matrix row dimension")]
+    /// Row value exceeds the matrix row dimension
     BadRowval,
     #[error("Bad column pointer values")]
+    /// Matrix column pointer values are defective
     BadColptr,
     #[error("sparsity pattern mismatch")]
+    /// Operation on matrices that have mismatching sparsity patterns
     SparsityMismatch,
 }
 

src/algebra/floats.rs

@@ -8,8 +8,10 @@ use crate::algebra::dense::BlasFloatT;
 /// Core traits for internal floating point values.
 ///
 /// This trait defines a subset of bounds for `FloatT`, which is preferred
-/// throughout for use in the solver.  When the "sdp" feature is enabled,
+/// throughout for use in the solver.  When the `sdp` feature is enabled,
 /// `FloatT` is additionally restricted to f32/f64 types supported by BLAS.
+/// When the `faer-sparse` feature is enabled, `FloatT` is additionally
+/// restricted to types implementing `RealField` from the `faer` crate.
 pub trait CoreFloatT:
     'static
     + Send
@@ -51,24 +53,32 @@ impl<T> CoreFloatT for T where
 
 cfg_if::cfg_if! {
     if #[cfg(feature="sdp")] {
+        /// A marker trait implemented on types supported by BLAS (i.e. f32 and f64)
+        /// when the package is compiled with the "sdp" feature using a BLAS/LAPACK library
+        #[doc(hidden)]
         pub trait MaybeBlasFloatT : BlasFloatT {}
         impl<T> MaybeBlasFloatT for T where T: BlasFloatT {}
     }
     else {
+        #[doc(hidden)]
         pub trait MaybeBlasFloatT {}
         impl<T> MaybeBlasFloatT for T {}
     }
 }
 
 // if "faer" is enabled, we must add an additional bound
-// to restrict compilation to Reals implementing SimpleEntity
+// to restrict compilation to types implementing RealField
 
 cfg_if::cfg_if! {
     if #[cfg(feature="faer-sparse")] {
+        #[doc(hidden)]
+        /// A marker trait implemented on types supported by faer-rs
+        /// when the package is compiled with the "faer-sparse" feature
         pub trait MaybeFaerFloatT : faer_traits::RealField {}
         impl<T> MaybeFaerFloatT for T where T: faer_traits::RealField {}
     }
     else {
+        #[doc(hidden)]
         pub trait MaybeFaerFloatT {}
         impl<T> MaybeFaerFloatT for T {}
     }
@@ -86,7 +96,7 @@ cfg_if::cfg_if! {
 pub trait FloatT: CoreFloatT + MaybeBlasFloatT + MaybeFaerFloatT {}
 impl<T> FloatT for T where T: CoreFloatT + MaybeBlasFloatT + MaybeFaerFloatT {}
 
-/// Trait for convering Rust primitives to [`FloatT`](crate::algebra::FloatT)
+/// Trait for converting Rust primitives to [`FloatT`](crate::algebra::FloatT)
 ///
 /// This convenience trait is implemented on f32/64 and u32/64.  This trait
 /// is required internally by the solver for converting constant primitives
@@ -97,7 +107,7 @@ impl<T> FloatT for T where T: CoreFloatT + MaybeBlasFloatT + MaybeFaerFloatT {}
 // NB: `AsFloatT` is a convenience trait for f32/64 and u32/64
 // so that we can do things like (2.0).as_T() everywhere on
 // constants, rather than the awful T::from_f32(2.0).unwrap()
-pub trait AsFloatT<T>: 'static {
+pub(crate) trait AsFloatT<T>: 'static {
     fn as_T(&self) -> T;
 }
 

src/algebra/math_traits.rs

@@ -63,7 +63,7 @@ pub trait VectorMath<T> {
     /// Dot product
     fn dot(&self, y: &Self) -> T;
 
-    // computes dot(z + αdz,s + αds) without intermediate allocation
+    /// computes dot(z + αdz,s + αds) without intermediate allocation
     fn dot_shifted(z: &[T], s: &[T], dz: &[T], ds: &[T], α: T) -> T;
 
     /// Standard Euclidian or 2-norm distance from `self` to `y`
@@ -93,7 +93,7 @@ pub trait VectorMath<T> {
     /// Inf-norm of an elementwise scaling of `self` by `v`
     fn norm_one_scaled(&self, v: &Self) -> T;
 
-    // Inf-norm of vector difference
+    /// Inf-norm of vector difference
     fn norm_inf_diff(&self, b: &Self) -> T;
 
     /// Minimum value in vector
@@ -152,7 +152,7 @@ pub trait MatrixMath<T> {
     fn col_norms_no_reset(&self, norms: &mut [T]);
 
     /// Compute columnwise infinity norm operations on
-    /// a symmstric matrix
+    /// a symmetric matrix
     fn col_norms_sym(&self, norms: &mut [T]);
 
     /// Compute columnwise infinity norm operations on

src/algebra/matrix_traits.rs

@@ -39,7 +39,7 @@ pub trait BlockConcatenate: Sized {
     /// Errors if column dimensions are incompatible
     fn vcat(A: &Self, B: &Self) -> Result<Self, MatrixConcatenationError>;
 
-    /// general block concatentation
+    /// general block concatenation
     fn hvcat(mats: &[&[&Self]]) -> Result<Self, MatrixConcatenationError>;
 
     /// block diagonal concatenation

src/algebra/sparsevector/mod.rs

@@ -15,7 +15,7 @@ pub(crate) struct SparseVector<T = f64> {
     pub nzval: Vec<T>,
 }
 
-/// Creates a SparseVector from a dense slice.
+/// Creates a `SparseVector` from a dense slice.
 impl<T> SparseVector<T>
 where
     T: Num + Copy,

src/lib.rs

@@ -55,6 +55,7 @@
 
 //Rust hates greek characters
 #![allow(confusable_idents)]
+#![warn(missing_docs)]
 
 const VERSION: &str = env!("CARGO_PKG_VERSION");
 
@@ -64,6 +65,9 @@ pub mod solver;
 pub(crate) mod stdio;
 pub mod timers;
 
+pub(crate) mod utils;
+pub use crate::utils::infbounds::*;
+
 #[cfg(feature = "python")]
 pub mod python;
 
@@ -79,7 +83,7 @@ macro_rules! printbuildenv {
     };
 }
 
-// print detailed build info to stdout
+/// print detailed build configuration info to stdout
 #[allow(clippy::explicit_write)]
 pub fn buildinfo() {
     use std::io::Write;
@@ -109,6 +113,8 @@ pub fn buildinfo() {
     writeln!(crate::stdio::stdout(), "no build info available").unwrap();
 }
 
+pub(crate) const _INFINITY_DEFAULT: f64 = 1e20;
+
 #[test]
 fn test_buildinfo() {
     buildinfo();

src/python/mod.rs

@@ -1,7 +1,7 @@
 //! Clarabel Python interface.
 //!
 //! This module implements a wrapper for the Rust version of Python using
-//! [PYO3](https://pyo3.rs/).   To build these wrappers from `cargo`, compile the crate with
+//! [PyO3](https://pyo3.rs/).   To build these wrappers from `cargo`, compile the crate with
 //! `--features python`.   This module has no public API.
 //!
 //! It should not normally be necessary to compile the Python wrapper from

src/python/module_py.rs

@@ -12,15 +12,15 @@ fn force_load_blas_lapack_py() {
 // get/set for the solver's internal infinity limit
 #[pyfunction(name = "get_infinity")]
 fn get_infinity_py() -> f64 {
-    crate::solver::get_infinity()
+    crate::get_infinity()
 }
 #[pyfunction(name = "set_infinity")]
 fn set_infinity_py(v: f64) {
-    crate::solver::set_infinity(v);
+    crate::set_infinity(v);
 }
 #[pyfunction(name = "default_infinity")]
 fn default_infinity_py() {
-    crate::solver::default_infinity();
+    crate::default_infinity();
 }
 #[pyfunction(name = "buildinfo")]
 fn buildinfo_py() {