doc: simplify and improve consistency (#263)

* update rust code doc

* simpler must_use attributes

* fix clippy lints

benches/Cargo.toml

@@ -30,18 +30,22 @@ rand = { workspace = true, features = ["small_rng"] }
 [[bin]]
 name = "builder"
 path = "src/builder.rs"
+doc = false
 
 [[bin]]
 name = "grisubal"
 path = "src/grisubal.rs"
+doc = false
 
 [[bin]]
 name = "shift"
 path = "src/shift.rs"
+doc = false
 
 [[bin]]
 name = "shift-nc"
 path = "src/shift_no_conflict.rs"
+doc = false
 
 # benches
 

benches/src/builder.rs

@@ -13,7 +13,7 @@ fn main() {
                     .lens([1.0, 1.0, 1.0])
                     .split_quads(split.is_some())
             }
-            _ => panic!("E: specifify at least the number of cells along X and Y axes"),
+            _ => panic!("E: specify at least the number of cells along X and Y axes"),
         }
     };
 

benches/src/lib.rs

@@ -1,17 +1,15 @@
 //! # honeycomb-benches
 //!
-//! This crate contains all benchmarks of the project. As a rule of thumb, the iai-callgrind
-//! benchmarks cover individual methods of the structure while criterion benchmarks cover higher
-//! level computations.
-//!
+//! This crate contains all benchmarks of the project. It also contains simple binaries used to
+//! profile and further optimize the implementation.
 //!
 //! ## Available benchmarks
 //!
 //! ### Criterion-based
 //!
 //! - `builder` - grid building routines at fixed size
 //! - `builder-grid-size` - grid building routines over a range of grid sizes
-//! - `fetch_icells` - `CMap2::fetch_<CELL>` methods
+//! - `fetch_icells` - `CMap2::iter_<CELL>` methods
 //! - `grisubal` - grisubal kernel with a fixed size grid
 //! - `grisubal-grid-size` - grisubal kernel over a range of grid granularity
 //! - `triangulate-quads` - triangulate all cells of a mixed-mesh
@@ -21,6 +19,14 @@
 //! - `prof-dim2-basic` - `CMap2` basic operations benchmarks
 //! - `prof-dim2-build` - `CMap2` constructor & building functions benchmarks
 //! - `prof-dim2-sewing-unsewing` - `CMap2` (un)sewing & (un)linking methods benchmarks
+//!
+//! ## Available binaries
+//!
+//! - `builder` - Build a 2-map grid using dimensions passed as argument
+//! - `grisubal` - Run the `grisubal` algorithm
+//! - `shift` - Run a simple vertex relaxation algorithm in parallel (naively)
+//! - `shift-nc` - Run a simple vertex relaxation algorithm in parallel (using independent set of
+//!   vertices)
 
 cfg_if::cfg_if! {
     if #[cfg(feature = "_single_precision")] {

examples/examples/parallel_shift.rs

@@ -7,7 +7,7 @@
 //! ```
 //!
 //! With `N_THREADS the number of thread used for execution. If it is not specified, or the
-//! argument can't be parsed, it will default to `std::thread::availqble_parallelism`, which in
+//! argument can't be parsed, it will default to `std::thread::available_parallelism`, which in
 //! turns default to `1` if it fails.
 //!
 //! # Description

examples/src/lib.rs

@@ -4,18 +4,19 @@
 //!
 //! ## Available examples
 //!
-//! ### Input / Output
+//! ### Algorithm
 //!
-//! - `io_read` -- Initialize and render a map from the VTK file passed to the command line.
-//! - `io_write` -- Serialize the map that is built by the `squaremap_split_some` becnhmark.
-//!   The file can be visualized using ParaView and compared to the render.
+//! - `grisubal` -- Run the grisubal algorithm on a specified input.
+//! - `parallel_shift` -- Run a simple parallel vertex relaxation routine that highlights usage of
+//!   the STM model.
 //!
-//! ### Utilities
+//! ### Input / Output
 //!
-//! - `memory_usage` -- Save the memory usage of a given map as three *csv* files. These files
-//!   can be used to generate charts using the `plot.py` script.
+//! - `io_read` -- Initialize and render a map from the VTK file passed to the command line.
+//! - `io_write` -- Serialize a map representing a grid with quads randomly split diagonally.
+//!   The output file can be visualized using ParaView and compared to the render.
 //!
 //! ### Rendering
 //!
 //! - `render` -- Render a map representing a simple orthogonal grid. Note that you may *need* to
-//!   run this example in release mode if the input mesh is large.
+//!   run this example in release mode.

honeycomb-core/src/attributes/collections.rs

@@ -12,20 +12,17 @@ use stm::{atomically, StmResult, TVar, Transaction};
 
 // ------ CONTENT
 
-/// Custom storage structure for attributes
+/// Custom storage structure
 ///
-/// This structured is used to store user-defined attributes using a vector of `Option<T>` items.
-/// This means that valid attributes value may be separated by an arbitrary number of `None`.
+/// **This structure is not meant to be used directly** but with the [`AttributeBind`] trait.
 ///
+/// The structure is used to store user-defined attributes using a vector of `Option<T>` items.
 /// This implementation should favor access logic over locality of reference.
 ///
 /// # Generics
 ///
 /// - `T: AttributeBind + AttributeUpdate` -- Type of the stored attributes.
 ///
-/// # Example
-///
-/// **This type is not meant to be used directly** but used along the [`AttributeBind`] trait.
 #[derive(Debug)]
 pub struct AttrSparseVec<T: AttributeBind + AttributeUpdate> {
     /// Inner storage.
@@ -34,6 +31,7 @@ pub struct AttrSparseVec<T: AttributeBind + AttributeUpdate> {
 
 #[doc(hidden)]
 impl<A: AttributeBind + AttributeUpdate> AttrSparseVec<A> {
+    /// Transactional write
     fn write_core(
         &self,
         trans: &mut Transaction,
@@ -43,10 +41,12 @@ impl<A: AttributeBind + AttributeUpdate> AttrSparseVec<A> {
         self.data[id.to_usize().unwrap()].replace(trans, Some(val))
     }
 
+    /// Transactional read
     fn read_core(&self, trans: &mut Transaction, id: &A::IdentifierType) -> StmResult<Option<A>> {
         self.data[id.to_usize().unwrap()].read(trans)
     }
 
+    /// Transactional remove
     fn remove_core(&self, trans: &mut Transaction, id: &A::IdentifierType) -> StmResult<Option<A>> {
         self.data[id.to_usize().unwrap()].replace(trans, None)
     }

honeycomb-core/src/attributes/manager.rs

@@ -50,8 +50,11 @@ macro_rules! get_storage_mut {
     };
 }
 
+// TODO: make the structure private & remove unused methods
 /// Main attribute storage structure.
 ///
+/// **This structure is not meant to be used directly**.
+///
 /// This structure is used to store all generic attributes that the user may add to the
 /// combinatorial map he's building.
 ///
@@ -153,11 +156,8 @@ impl AttrStorageManager {
     ///
     /// # Arguments
     ///
-    /// - `size: usize` -- Initial size of the new storage.
-    ///
-    /// ## Generic
-    ///
     /// - `A: AttributeBind + 'static` -- Type of the attribute that will be stored.
+    /// - `size: usize` -- Initial size of the new storage.
     ///
     /// # Panics
     ///
@@ -189,11 +189,9 @@ impl AttrStorageManager {
     ///
     /// # Arguments
     ///
+    /// - `A: AttributeBind` -- Attribute of which the storage should be extended.
     /// - `length: usize` -- Length by which the storage should be extended.
     ///
-    /// ## Generic
-    ///
-    /// - `A: AttributeBind` -- Attribute of which the storage should be extended.
     pub fn extend_storage<A: AttributeBind>(&mut self, length: usize) {
         get_storage_mut!(self, storage);
         if let Some(st) = storage {
@@ -208,7 +206,7 @@ impl AttrStorageManager {
 
     /// Get a reference to the storage of a given attribute.
     ///
-    /// # Generic
+    /// # Arguments
     ///
     /// - `A: AttributeBind` -- Attribute stored by the fetched storage.
     ///
@@ -217,7 +215,7 @@ impl AttrStorageManager {
     /// This method may panic if:
     /// - there's no storage associated with the specified attribute
     /// - downcasting `Box<dyn UnknownAttributeStorage>` to `<A as AttributeBind>::StorageType` fails
-    #[must_use = "unused getter result - please remove this method call"]
+    #[must_use = "unused return value"]
     pub fn get_storage<A: AttributeBind>(&self) -> Option<&<A as AttributeBind>::StorageType> {
         let probably_storage = match A::BIND_POLICY {
             OrbitPolicy::Vertex | OrbitPolicy::VertexLinear => &self.vertices[&TypeId::of::<A>()],
@@ -233,7 +231,7 @@ impl AttrStorageManager {
     /// This method is useful when implementing routines that uses attributes to run; Those can then be removed
     /// before the final result is returned.
     ///
-    /// # Generic
+    /// # Arguments
     ///
     /// - `A: AttributeBind` -- Attribute stored by the fetched storage.
     pub fn remove_storage<A: AttributeBind>(&mut self) {

honeycomb-core/src/attributes/mod.rs

@@ -2,8 +2,6 @@
 //!
 //! This module contains all code related to generic attribute modelling and handling.
 
-// ------ MODULE DECLARATIONS
-
 mod collections;
 mod manager;
 mod traits;