doc(core): complete CMap3 documentation

I forgot there was an `#[allow()]` in there

Author: imrn99

honeycomb-core/src/cmap/dim3/basic_ops.rs

@@ -22,7 +22,12 @@ use crate::stm::{StmClosureResult, StmError, Transaction, atomically};
 // not applied to orbit currently bc they are lazily onsumed, and therefore require dedicated
 // instances to be robust
 thread_local! {
-    static AUXILIARIES: RefCell<(VecDeque<DartIdType>, HashSet<DartIdType>)> = RefCell::new((VecDeque::with_capacity(10), HashSet::with_capacity(10)));
+    static AUXILIARIES: RefCell<(VecDeque<DartIdType>, HashSet<DartIdType>)> = RefCell::new(
+        (
+            VecDeque::with_capacity(10),
+            HashSet::with_capacity(10),
+        )
+    );
 }
 
 /// **Beta-related methods**
@@ -138,6 +143,12 @@ impl<T: CoordsFloat> CMap3<T> {
     /// # Return
     ///
     /// Return a boolean indicating if the dart is 0-free, 1-free **and** 2-free.
+    ///
+    /// # Errors
+    ///
+    /// This method is meant to be called in a context where the returned `Result` is used to
+    /// validate the transaction passed as argument. Errors should not be processed manually,
+    /// only processed via the `?` operator.
     #[must_use = "unused return value"]
     pub fn is_free_tx(&self, t: &mut Transaction, dart_id: DartIdType) -> StmClosureResult<bool> {
         Ok(self.beta_tx::<0>(t, dart_id)? == NULL_DART_ID
@@ -417,6 +428,7 @@ impl<T: CoordsFloat> CMap3<T> {
     }
 
     /// Return an iterator over IDs of all the map's vertices.
+    #[must_use = "iterators are lazy and do nothing unless consumed"]
     pub fn par_iter_vertices(&self) -> impl ParallelIterator<Item = VertexIdType> + '_ {
         (1..self.n_darts() as DartIdType)
             .into_par_iter()
@@ -434,6 +446,7 @@ impl<T: CoordsFloat> CMap3<T> {
     }
 
     /// Return an iterator over IDs of all the map's edges.
+    #[must_use = "iterators are lazy and do nothing unless consumed"]
     pub fn par_iter_edges(&self) -> impl ParallelIterator<Item = EdgeIdType> + '_ {
         (1..self.n_darts() as DartIdType)
             .into_par_iter()
@@ -451,6 +464,7 @@ impl<T: CoordsFloat> CMap3<T> {
     }
 
     /// Return an iterator over IDs of all the map's faces.
+    #[must_use = "iterators are lazy and do nothing unless consumed"]
     pub fn par_iter_faces(&self) -> impl ParallelIterator<Item = FaceIdType> + '_ {
         (1..self.n_darts() as DartIdType)
             .into_par_iter()
@@ -468,6 +482,7 @@ impl<T: CoordsFloat> CMap3<T> {
     }
 
     /// Return an iterator over IDs of all the map's volumes.
+    #[must_use = "iterators are lazy and do nothing unless consumed"]
     pub fn par_iter_volumes(&self) -> impl ParallelIterator<Item = VolumeIdType> + '_ {
         (1..self.n_darts() as DartIdType)
             .into_par_iter()

honeycomb-core/src/cmap/dim3/links/mod.rs

@@ -32,6 +32,9 @@ impl<T: CoordsFloat> CMap3<T> {
     /// `?` operator. The policy in case of failure can be defined when creating the transaction,
     /// using `Transaction::with_control`.
     ///
+    /// It may return an error if the transaction fails or if the link fails; See [`LinkError`] for
+    /// more detail about the latter.
+    ///
     /// # Panics
     ///
     /// The method may panic if:
@@ -104,6 +107,17 @@ impl<T: CoordsFloat> CMap3<T> {
     ///
     /// This variant is equivalent to [`link`][Self::link], but internally uses a transaction that
     /// will be retried until validated.
+    ///
+    /// # Errors
+    ///
+    /// It may return an error if the transaction fails or if the link fails; See [`LinkError`] for
+    /// more detail about the latter.
+    ///
+    /// # Panics
+    ///
+    /// The method may panic if:
+    /// - `I >= 4` or `I == 0`,
+    /// - `lhs_dart_id` is already `I`-free.
     pub fn force_link<const I: u8>(
         &self,
         lhs_dart_id: DartIdType,
@@ -124,6 +138,17 @@ impl<T: CoordsFloat> CMap3<T> {
     ///
     /// This variant is equivalent to [`unlink`][Self::unlink], but internally uses a transaction
     /// that will be retried until validated.
+    ///
+    /// # Errors
+    ///
+    /// It may return an error if the transaction fails or if the link fails; See [`LinkError`] for
+    /// more detail about the latter.
+    ///
+    /// # Panics
+    ///
+    /// The method may panic if:
+    /// - `I >= 4` or `I == 0`,
+    /// - `lhs_dart_id` is already `I`-free.
     pub fn force_unlink<const I: u8>(&self, lhs_dart_id: DartIdType) -> Result<(), LinkError> {
         // these assertions + match on a const are optimized away
         assert!(I < 4);

honeycomb-core/src/cmap/dim3/serialize.rs

@@ -10,6 +10,10 @@ impl<T: CoordsFloat> CMap3<T> {
     /// Serialize the map under a custom format.
     ///
     /// The format specification is described in the [user guide]().
+    ///
+    /// # Panics
+    ///
+    /// This method may panic if there was an error trying to open / write to the file.
     pub fn serialize(&self, mut writer: impl std::fmt::Write) {
         let n_darts = self.n_darts();
 
@@ -95,9 +99,15 @@ impl<T: CoordsFloat> CMap3<T> {
                 writeln!(
                     writer,
                     "{v} {} {} {}",
-                    val.0.to_f64().unwrap(),
-                    val.1.to_f64().unwrap(),
-                    val.2.to_f64().unwrap(),
+                    val.0
+                        .to_f64()
+                        .expect("E: unreachable, unless experimenting with f128"),
+                    val.1
+                        .to_f64()
+                        .expect("E: unreachable, unless experimenting with f128"),
+                    val.2
+                        .to_f64()
+                        .expect("E: unreachable, unless experimenting with f128"),
                 )
                 .expect("E: couldn't write to file");
             }

honeycomb-core/src/cmap/mod.rs

@@ -3,7 +3,6 @@
 mod builder;
 mod components;
 mod dim2;
-#[allow(missing_docs, clippy::missing_errors_doc, clippy::missing_panics_doc)] // FIXME:write docs
 mod dim3;
 mod error;