docs: write more documentation

src/lib.rs

@@ -1,3 +1,23 @@
+//! Abstraction and APIs for matrix operations
+//!
+//! Includes handy utilities such as:
+//! - Transpose of matrix
+//! - Determinant of any N-by-N matrix
+//! - Matrix mathematics
+//! - TODO:: Inverse matrix
+//! - TODO:: Transformation of vectors using matrices
+//!
+//! Examples:
+//! ```
+//! ...
+//! use matrix::Matrix;
+//! let m = Matrix::from_str("1,2,3\n4,5,6\n7,8,9");
+//! println!("Matrix string formatting:\n{}", m);
+//! println!("Evaluate determinant of matrix: {}", m.determinant());
+//! println!("Transpose of matrix m:\n{}", m.transpose());
+//! ...
+//! ```
+
 pub mod types;
 
 #[cfg(test)]

src/types.rs

@@ -1,5 +1,8 @@
-//! Type definition crate for the program
-//! Contains a Matrix definition
+//! Matrix-related type definitions
+//!
+//! Includes modules:
+//! - Matrix 
+//! - Matrix parse and arithmetic errors
 
 pub mod matrix;
 pub mod matrix_err;

src/types/matrix.rs

@@ -1,16 +1,29 @@
+//! Matrix struct and relevant implementations.
+//!
+//! Example usage - addition of two matrices:
+//! ```
+//! use matrix::Matrix;
+//! let m1 = Matrix::from_str("1,1,1\n1,1,1\n1,1,1");
+//! let m2 = Matrix::from_str("2,2,2\n2,2,2\n2,2,2");
+//! println!("Sum of m1 + m2: \n{}", m1 + m2);
+//! ```
+//!
+//! TODO:: Create matrix multiplication method
+
 use std::{fmt::Display, ops::Add, str::FromStr};
 
 use super::matrix_err::{MatrixSetValueError, ParseMatrixError};
-/// A Matrix struct
-///
-/// 
 #[derive(Debug, PartialEq, Eq)]
 pub struct Matrix {
+    /// Number of rows in matrix.
     pub nrows: usize,
-    pub ncols: usize,
-    pub data: Vec<Vec<i32>>,
-}
     
+    /// Number of columns in matrix.
+    pub ncols: usize,
+    
+    /// Data stored in the matrix, you should not access this directly
+    data: Vec<Vec<i32>>,
+}
 
 impl FromStr for Matrix {
     type Err = ParseMatrixError;
@@ -28,7 +41,7 @@ impl FromStr for Matrix {
             }
             d.push(r);
         }
-       Ok(Matrix::new(d))
+        Ok(Matrix::new(d))
     }
 }
 
@@ -57,7 +70,9 @@ impl Display for Matrix {
 impl<'a, 'b> Add<&'b Matrix> for &'a Matrix {
     type Output = Matrix;
     fn add(self, rhs: &'b Matrix) -> Self::Output {
-        if (self.nrows != rhs.nrows) || (self.ncols != rhs.ncols) { panic!("Cannot add two matrices with different dimensions"); }
+        if (self.nrows != rhs.nrows) || (self.ncols != rhs.ncols) {
+            panic!("Cannot add two matrices with different dimensions");
+        }
         let mut x = Matrix {
             nrows: self.nrows,
             ncols: self.ncols,
@@ -72,10 +87,13 @@ impl<'a, 'b> Add<&'b Matrix> for &'a Matrix {
     }
 }
 
-
 impl Matrix {
-
-    /// Matrix initialiser function
+    /// Matrix initialiser function.
+    ///
+    /// Accepts a new array of data as a list of rows.
+    ///
+    /// TODOs
+    /// - Add row length check
     pub fn new(data: Vec<Vec<i32>>) -> Matrix {
         Matrix {
             nrows: data.len(),
@@ -83,15 +101,30 @@ impl Matrix {
             data,
         }
     }
+
+    /// Query one element at selected position.
+    ///
+    /// Returns `None` if index is out of bounds.
     pub fn get(&self, row_index: usize, column_index: usize) -> Option<i32> {
         let r = self.data.get(row_index)?;
         let n = r.get(column_index)?;
         Some(*n)
     }
-    pub fn set(&mut self, row_index: usize, column_index: usize, new_data: i32) -> Result<(), MatrixSetValueError> {
+
+    /// Update one element at selected position.
+    ///
+    /// Returns `Err()` if index is out of bounds.
+    pub fn set(
+        &mut self,
+        row_index: usize,
+        column_index: usize,
+        new_data: i32,
+    ) -> Result<(), MatrixSetValueError> {
         self.data[row_index][column_index] = new_data;
         Ok(())
     }
+
+    /// Checks if this is a square matrix.
     pub fn is_square(&self) -> bool {
         self.nrows == self.ncols
     }
@@ -112,8 +145,14 @@ impl Matrix {
         }
         Matrix::new(data)
     }
+
+    /// Evaluates any N-by-N matrix.
+    ///
+    /// This function panics if the matrix is not square!
     pub fn determinant(&self) -> i32 {
-        if !self.is_square() { panic!() };
+        if !self.is_square() {
+            panic!()
+        };
         if self.nrows == 2 && self.ncols == 2 {
             return self.data[0][0] * self.data[1][1] - self.data[0][1] * self.data[1][0];
         }
@@ -121,12 +160,14 @@ impl Matrix {
         for (i, n) in self.data[0].iter().enumerate() {
             let mult = if i % 2 == 0 { -*n } else { *n };
             let eval = self.splice(i).determinant();
-            // println!("tmp result: {}", mult * eval);
             tmp += mult * eval;
-            // println!("tmp: {}", tmp);
         }
         tmp
     }
+
+    /// Evaluates the tranpose of the matrix.
+    ///
+    /// Each row becomes a column, each column becomes a row.
     pub fn transpose(&self) -> Matrix {
         let mut new_data = Vec::<Vec<i32>>::new();
         for i in 0..self.nrows {