WIP: Documentation

src/lib.rs

@@ -1,4 +1,36 @@
 //! A Rust native linear algebra library
+//! 
+//! The goal of `householder` is the development of a Rust native
+//! linear algebra library that is performant and does not require
+//! external BLAS/Lapack linkage or dependencies.
+//! 
+//! The library is early stage. The core data structures are implemented
+//! and functionality is continuously being added.
+//! 
+//! The core of `householder` is the [Matrix](crate::matrix::Matrix) type,
+//! which supports fixed size implementations, dynamic size implementations,
+//! and specialises also to vectors. It is agnostic to underlying storage
+//! layouts (i.e. row or column major) and also supports layouts with
+//! arbitrary strides.
+//! 
+//! Algebraic operations on matrices are implemented using a system that is akin
+//! to expression templates. Adding matrices or multiplying them with a scalar
+//! is not immediately executed but creates a new type that stores the information
+//! about the operation. Only when the user asks for the evaluation, all operations
+//! are executed in a single pass without creating temporaries.
+//! 
+//! Matrix-matrix products are implemented through the [matrixmultiply](matrixmultiply)
+//! crate. We are in the process of implementing more advanced linear algebra routines
+//! (e.g. LU, QR, etc.). But these are not yet available. The focus is on implementing
+//! modern blocked multi-threaded routines whose performance is competitive with Lapack.
+//! 
+//! To learn more about `householder` we recommend the user to read the following bits
+//! of information.
+//! 
+//! - [Basic trait definitions](crate::traits)
+//! - [Matrix storage layouts](crate::layouts)
+//! - [The Matrix type](crate::matrix)
+//! - Examples
 
 pub mod data_container;
 pub mod types;
@@ -12,16 +44,6 @@ pub mod matrix_ref;
 pub mod scalar_mult;
 pub mod addition;
 pub mod tools;
-
-//pub mod traits;
-//pub mod slice_matrix;
-//pub mod matrix;
-//pub mod base_types;
-//pub mod matrix_operators;
-//pub mod macros;
-//pub mod iterators;
-//pub mod scalar_mult;
-//pub mod addition;
 pub mod matrix_multiply;
 
 pub use cauchy::Scalar;

src/traits.rs

@@ -1,4 +1,14 @@
-//! Basic traits for matrices
+//! Trait definitions
+//! 
+//! `householder` relies heavily on traits. This module
+//! collects the core trait definitions to define a matrix type.
+//! The following functionality is available through traits.
+//! 
+//! - [Definition of random access operations.](random_access)
+//! - [Size type descriptions (e.g. fixed given dimenion or dynamically allocated).](size)
+//! - [Matrix storage layout.](layout)
+//! - [Summary trait defining a matrix.](matrix)
+ 
 pub mod random_access;
 pub mod size;
 pub mod layout;

src/traits/random_access.rs

@@ -1,25 +1,54 @@
 //! Traits for random access of matrices
+//! 
+//! The traits in this module define safe and unsafe random access
+//! methods for a matrix. The user needs to implement `UnsafeRandomAccess`
+//! and `UnsafeRandomAccessMut` (for mutable access). The corresponding safe
+//! traits `SafeRandomAccess` and `SafeRandomAccessMut` are then auto-implemented.
+//! The safe traits check at runtime whether an index is out of bounds.
+//! 
+//! Each trait provides a two-dimensional and a one-dimensional access method,
+//! namely `get` and `get1d` (together with their mutable and unsafe variants).
+//! The two-dimensional access takes a row and a column and returns the corresponding
+//! matrix element. The one-dimensional access takes a single 
+//! 
+//! The one-dimensional access
+//! takes a single `index` parameter that iterates through the matrix elements.
+//! If also the [LayoutType](crate::traits::LayoutType) is implemented, it is
+//! recommended to use the [convert_1d_raw](crate::traits::LayoutType::convert_1d_raw)
+//! functions from that trait to implement `get1d` to ensure compatibility with
+//! the memory layout defined in that trait.
 
 use crate::types::{IndexType, Scalar};
 use crate::traits::{Layout, LayoutType};
 
-/// Random access without bounds check for matrices.
+
+/// This trait provides unsafe access to the underlying data. See 
+/// [Random Access](crate::traits::random_access) for a description.
 pub trait UnsafeRandomAccess {
     type Item: Scalar;
 
+    /// Return the element at position (`row`, `col`).
     unsafe fn get_unchecked(&self, row: IndexType, col: IndexType) -> Self::Item;
+
+    /// Return the element at position `index` in one-dimensional numbering.
     unsafe fn get1d_unchecked(&self, index: IndexType) -> Self::Item;
 }
 
-/// Get mutable access to element without bounds check.
+/// This trait provides unsafe mutable access to the underlying data. See 
+/// [Random Access](crate::traits::random_access) for a description.
 pub trait UnsafeRandomAccessMut {
     type Item: Scalar;
 
+    /// Return a mutable reference to the element at position (`row`, `col`).
     unsafe fn get_unchecked_mut(&mut self, row: IndexType, col: IndexType) -> &mut Self::Item;
+
+    /// Return a mutable reference at position `index` in one-dimensional numbering.
     unsafe fn get1d_unchecked_mut(&mut self, index: IndexType) -> &mut Self::Item;
 }
 
-/// Bounds checked random access for matrices.
+/// This trait provides bounds checked access to the underlying data. See 
+/// [Random Access](crate::traits::random_access) for a description. It depends
+/// on the [Layout](crate::traits::Layout) trait to obtain dimension information.
 pub trait RandomAccess: UnsafeRandomAccess + Layout {
     /// Get the element at position (row, col) of the matrix.
     fn get(&self, row: usize, col: usize) -> Self::Item;