Add documentation

Rustdoc is amazing!

Cargo.toml

@@ -11,4 +11,4 @@ uuid = { version = "1.6.1", features = ["v4", "fast-rng", "macro-diagnostics"] }
 [lints.rust]
 unsafe_code = "forbid"
 dead_code = "allow"
-#missing_docs = "warn"
+missing_docs = "warn"

cspell.json

@@ -9,6 +9,8 @@
         "clippy",
         "codecov",
         "nocapture",
+        "simplicial",
+        "spacelike",
         "Voronoi"
     ],
     "ignoreWords": [],

src/delaunay_core/cell.rs

@@ -1,16 +1,48 @@
+//! Data and operations on d-dimensional cells or [simplices](https://en.wikipedia.org/wiki/Simplex).
+
 use uuid::Uuid;
 
 use super::{utilities::make_uuid, vertex::Vertex};
 
 #[derive(Debug, Clone)]
+/// The `Cell` struct represents a d-dimensional [simplex](https://en.wikipedia.org/wiki/Simplex)
+/// with vertices, a unique identifier, optional neighbors, and optional data.
+///
+/// # Properties:
+///
+/// * `vertices`: A vector of vertices. Each `Vertex`` has a type T, optional data U, and a constant
+/// D representing the number of dimensions.
+/// * `uuid`: The `uuid` property is of type `Uuid` and represents a universally unique identifier for
+/// a `Cell`. It is used to uniquely identify each instance of a `Cell`.
+/// * `neighbors`: The `neighbors` property is an optional vector of `Uuid` values. It represents the
+/// UUIDs of the neighboring cells that are connected to the current cell.
+/// * `data`: The `data` property is an optional field that can hold a value of type `V`. It allows
+/// storage of additional data associated with the `Cell`.
 pub struct Cell<T, U, V, const D: usize> {
+    /// The vertices of the cell.
     pub vertices: Vec<Vertex<T, U, D>>,
+    /// The unique identifier of the cell.
     pub uuid: Uuid,
+    /// The neighboring cells connected to the current cell.
     pub neighbors: Option<Vec<Uuid>>,
+    /// The optional data associated with the cell.
     pub data: Option<V>,
 }
 
 impl<T, U, V, const D: usize> Cell<T, U, V, D> {
+    /// The function `new` creates a new `Cell`` object with the given vertices.
+    /// A D-dimensional cell has D + 1 vertices, so the number of vertices must be less than or equal to D + 1.
+    ///
+    /// # Arguments:
+    ///
+    /// * `vertices`: The `vertices` parameter is a vector of `Vertex<T, U, D>` objects.
+    ///
+    /// # Returns:
+    ///
+    /// a `Result` type. If the condition `vertices.len() > D + 1` is true, it returns an `Err` variant
+    /// with the message "Number of vertices must be less than or equal to D + 1". Otherwise, it returns
+    /// an `Ok` variant with a `Cell` containing the provided `vertices`, a generated `uuid`, and
+    /// optional neighbor and data fields. Neighbors will be calculated by the `delaunay_core::triangulation_data_structure::Tds`.
     pub fn new(vertices: Vec<Vertex<T, U, D>>) -> Result<Self, &'static str> {
         if vertices.len() > D + 1 {
             return Err("Number of vertices must be less than or equal to D + 1");
@@ -26,6 +58,21 @@ impl<T, U, V, const D: usize> Cell<T, U, V, D> {
         })
     }
 
+    /// The function `new_with_data` creates a new `Cell` object with the given vertices and data.
+    /// A D-dimensional cell has D + 1 vertices, so the number of vertices must be less than or equal to D + 1.
+    ///
+    /// # Arguments:
+    ///
+    /// * `vertices`: The `vertices` parameter is a vector of `Vertex<T, U, D>` objects.
+    /// * `data`: The `data` parameter is of type `V`. It represents the data associated with the cell.
+    ///
+    /// # Returns:
+    ///
+    /// a `Result` type. If the condition `vertices.len() > D + 1` is true, it returns an `Err` variant
+    /// with the message "Number of vertices must be less than or equal to D + 1". Otherwise, it returns
+    /// an `Ok` variant with a `Cell` containing the provided `vertices`, a generated `uuid`, the
+    /// provided data, and optional neighbor fields which will be later be calculated by the
+    /// `delaunay_core::triangulation_data_structure::Tds`.
     pub fn new_with_data(vertices: Vec<Vertex<T, U, D>>, data: V) -> Result<Self, &'static str> {
         if vertices.len() > D + 1 {
             return Err("Number of vertices must be less than or equal to D + 1");
@@ -41,10 +88,21 @@ impl<T, U, V, const D: usize> Cell<T, U, V, D> {
         })
     }
 
+    /// The function returns the number of vertices in the `Cell`.
+    ///
+    /// # Returns:
+    ///
+    /// The number of vertices in the `Cell`.
     pub fn number_of_vertices(&self) -> usize {
         self.vertices.len()
     }
 
+    /// The `dim` function returns the dimensionality of the `Cell`.
+    ///
+    /// # Returns:
+    ///
+    /// The `dim` function returns the dimension, which is calculated by subtracting 1 from
+    /// the number of vertices in the `Cell`.
     pub fn dim(&self) -> usize {
         self.number_of_vertices() - 1
     }

src/delaunay_core/point.rs

@@ -1,13 +1,54 @@
+//! Data and operations on d-dimensional points.
+
 #[derive(Debug, PartialEq, Clone, Copy)]
+/// The `Point` struct represents a point in a D-dimensional space, where the coordinates are of type
+/// `T`.
+///
+/// # Properties:
+///
+/// * `coords`: `coords` is a public property of the `Point`. It is an array of type `T` with a
+/// length of `D`. The type `T` is a generic type parameter, which means it can be any type. The length
+/// `D` is a constant unsigned integer, which means it cannot be changed and is known at compile time.
 pub struct Point<T, const D: usize> {
+    /// The coordinates of the point.
     pub coords: [T; D],
 }
 
 impl<T: Clone, const D: usize> Point<T, D> {
+    /// The function `new` creates a new instance of a `Point` with the given coordinates.
+    ///
+    /// # Arguments:
+    ///
+    /// * `coords`: The `coords` parameter is an array of type `T` with a length of `D`.
+    ///
+    /// # Returns:
+    ///
+    /// The `new` function returns an instance of the `Point`.
+    /// 
+    /// # Examples
+    /// 
+    /// ```
+    /// use d_delaunay::delaunay_core::point::Point;
+    /// let point = Point::new([1.0, 2.0, 3.0, 4.0]);
+    /// assert_eq!(point.coords, [1.0, 2.0, 3.0, 4.0]);
+    /// ```
     pub fn new(coords: [T; D]) -> Self {
         Self { coords }
     }
 
+    /// The `dim` function returns the dimensionality of the `Point`.
+    ///
+    /// # Returns:
+    ///
+    /// The `dim` function is returning the value of `D`, which the number of coordinates.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use d_delaunay::delaunay_core::point::Point;
+    /// let point = Point::new([1.0, 2.0, 3.0, 4.0]);
+    /// assert_eq!(point.dim(), 4);
+    /// ```
     pub fn dim(&self) -> usize {
         D
     }

src/delaunay_core/triangulation_data_structure.rs

@@ -1,21 +1,74 @@
+//! Data and operations on d-dimensional triangulation data structures.
+//! 
+//! Intended to match functionality of [CGAL Triangulations](https://doc.cgal.org/latest/Triangulation/index.html).
+
 use super::{cell::Cell, point::Point, vertex::Vertex};
 use std::cmp::PartialEq;
 use std::{cmp::min, collections::HashMap};
 use uuid::Uuid;
 
 #[derive(Debug, Clone)]
+/// The `Tds` struct represents a triangulation data structure with vertices and cells, where the vertices
+/// and cells are identified by UUIDs.
+///
+/// # Properties:
+///
+/// * `vertices`: A HashMap that stores vertices with their corresponding UUIDs as keys. Each `Vertex` has
+/// a `Point` of type T, vertex data of type U, and a constant D representing the dimension.
+/// * `cells`: The `cells` property is a `HashMap` that stores `Cell` objects. Each `Cell` has
+/// one or more `Vertex<T, U, D>` with cell data of type V. Note the dimensionality of the cell may differ
+/// from D, though the TDS only stores cells of maximal dimensionality D and infers other lower dimensional
+/// cells from the maximal cells and their vertices.
+///
+/// For example, in 3 dimensions:
+///
+/// * A 0-dimensional cell is a `Vertex`.
+/// * A 1-dimensional cell is an `Edge` given by the `Tetrahedron` and two `Vertex` endpoints.
+/// * A 2-dimensional cell is a `Facet` given by the `Tetrahedron` and the opposite `Vertex`.
+/// * A 3-dimensional cell is a `Tetrahedron`, the maximal cell.
+///
+/// A similar pattern holds for higher dimensions.
+///
+/// In general, vertices are embedded into D-dimensional Euclidean space, and so the `Tds` is a finite simplicial complex.
 pub struct Tds<T, U, V, const D: usize> {
+    /// A HashMap that stores vertices with their corresponding UUIDs as keys.
+    /// Each `Vertex` has a `Point` of type T, vertex data of type U, and a constant D representing the dimension.
     pub vertices: HashMap<Uuid, Vertex<T, U, D>>,
+
+    /// The `cells` property is a `HashMap` that stores `Cell` objects.
+    /// Each `Cell` has one or more `Vertex<T, U, D>` with cell data of type V.
+    /// Note the dimensionality of the cell may differ from D, though the TDS only stores cells of maximal dimensionality D
+    /// and infers other lower dimensional cells from the maximal cells and their vertices.
     pub cells: HashMap<Uuid, Cell<T, U, V, D>>,
 }
 
 impl<T, U, V, const D: usize> Tds<T, U, V, D> {
+    /// The function creates a new instance of a triangulation data structure with given points, initializing the vertices and
+    /// cells.
+    ///
+    /// # Arguments:
+    ///
+    /// * `points`: A vector of points.
+    ///
+    /// # Returns:
+    ///
+    /// The `new` function returns a Tds.
     pub fn new(points: Vec<Point<T, D>>) -> Self {
         let vertices = Vertex::into_hashmap(Vertex::from_points(points));
         let cells = HashMap::new();
         Self { vertices, cells }
     }
 
+    /// The `add` function checks if a vertex with the same coordinates already exists in a hashmap, and
+    /// if not, inserts the vertex into the hashmap.
+    ///
+    /// # Arguments:
+    ///
+    /// * `vertex`: The `vertex` parameter is of type `Vertex<T, U, D>`.
+    ///
+    /// # Returns:
+    ///
+    /// The function `add` returns a `Result<(), &'static str>`.
     pub fn add(&mut self, vertex: Vertex<T, U, D>) -> Result<(), &'static str>
     where
         T: PartialEq,
@@ -36,21 +89,42 @@ impl<T, U, V, const D: usize> Tds<T, U, V, D> {
         }
     }
 
+    /// The function returns the number of vertices in the triangulation data structure.
+    ///
+    /// # Returns:
+    ///
+    /// The number of vertices in the Tds.
     pub fn number_of_vertices(&self) -> usize {
         self.vertices.len()
     }
 
+    /// The `dim` function returns the minimum value between the number of vertices minus one and the
+    /// value of `D` as an `i32`.
+    ///
+    /// # Returns:
+    ///
+    /// The `dim` function returns an `i32` value.
     pub fn dim(&self) -> i32 {
         let len = self.number_of_vertices() as i32;
 
         min(len - 1, D as i32)
     }
 
+    /// The function `number_of_cells` returns the number of cells in a triangulation data structure.
+    ///
+    /// # Returns:
+    ///
+    /// The number of cells in the Tds.
     pub fn number_of_cells(&self) -> usize {
         self.cells.len()
     }
 }
 
+/// The function "start" will eventually return a triangulation data structure.
+///
+/// # Returns:
+///
+/// The function `start()` is returning an `i32` value of `1`.
 pub fn start() -> i32 {
     println!("Starting ...");
     1

src/delaunay_core/utilities.rs

@@ -1,5 +1,13 @@
+//! Utility functions
+
 use uuid::Uuid;
 
+/// The function `make_uuid` generates a version 4 UUID in Rust.
+///
+/// # Returns:
+///
+/// a randomly generated UUID (Universally Unique Identifier) using the `new_v4` method from the `Uuid`
+/// struct.
 pub fn make_uuid() -> Uuid {
     Uuid::new_v4()
 }