Update doc strings

Author: w1th0utnam3

splashsurf_lib/src/lib.rs

@@ -12,6 +12,10 @@
 //!  In particular it adds `From` impls for the [mesh](crate::mesh) types used by this crate to convert them to
 //!  [`vtkio::model::UnstructuredGridPiece`](https://docs.rs/vtkio/0.6.*/vtkio/model/struct.UnstructuredGridPiece.html) and [`vtkio::model::DataSet`](https://docs.rs/vtkio/0.6.*/vtkio/model/enum.DataSet.html)
 //!  types. If the feature is enabled, The crate exposes its `vtkio` dependency as `splashsurflib::vtkio`.
+//! - **`io`**: Enables the [`io`] module, containing functions to load and store particle and mesh files
+//!  from various file formats, e.g. `VTK`, `OBJ`, `BGEO` etc. This feature implies the `vtk_extras` feature.
+//!  It is disabled by default because a pure "online" surface reconstruction might not need any file IO.
+//!  The feature adds several dependencies to support the file formats.
 //! - **`profiling`**: Enables profiling of internal functions. The resulting data can be displayed using the functions
 //!  from the [`profiling`] module. Furthermore, it exposes the [`profile`] macro that can be used e.g.
 //!  by binary crates calling into this library to add their own profiling scopes to the measurements.
@@ -160,7 +164,7 @@ pub enum ParticleDensityComputationStrategy {
 }
 
 impl<R: Real> SpatialDecompositionParameters<R> {
-    /// Tries to convert the parameters from one [Real] type to another [Real] type, returns None if conversion fails
+    /// Tries to convert the parameters from one [`Real`] type to another [`Real`] type, returns `None` if conversion fails
     pub fn try_convert<T: Real>(&self) -> Option<SpatialDecompositionParameters<T>> {
         Some(SpatialDecompositionParameters {
             subdivision_criterion: self.subdivision_criterion.clone(),
@@ -265,7 +269,7 @@ impl<I: Index, R: Real> SurfaceReconstruction<I, R> {
         self.particle_densities.as_ref()
     }
 
-    /// Returns a reference to the virtual background grid that was used as a basis for discretization of the density map for marching cubes, can be used to convert the density map to a hex mesh (using [sparse_density_map_to_hex_mesh](density_map::sparse_density_map_to_hex_mesh))
+    /// Returns a reference to the virtual background grid that was used as a basis for discretization of the density map for marching cubes, can be used to convert the density map to a hex mesh (using [`density_map::sparse_density_map_to_hex_mesh`])
     pub fn grid(&self) -> &UniformGrid<I, R> {
         &self.grid
     }

splashsurf_lib/src/octree.rs

@@ -833,7 +833,7 @@ impl<I: Index, R: Real> NodeData<I, R> {
     }
 }
 
-/// Returns the [PointIndex] of the octree subdivision point for an [OctreeNode] with the given lower and upper points
+/// Returns the [`PointIndex`] of the octree subdivision point for an [`OctreeNode`] with the given lower and upper points
 fn get_split_point<I: Index, R: Real>(
     grid: &UniformGrid<I, R>,
     lower: &PointIndex<I>,

splashsurf_lib/src/traits.rs

@@ -31,17 +31,17 @@ pub trait Index:
     + ThreadSafe
     + 'static
 {
-    /// Converts the value to the specified [Real] type. If the value cannot be represented by the target type, `None` is returned.
+    /// Converts this value to the specified [`Real`] type `T` by converting first to `f64` followed by `T::from_f64`. If the value cannot be represented by the target type, `None` is returned.
     fn to_real<R: Real>(self) -> Option<R> {
         R::from_f64(self.to_f64()?)
     }
 
-    /// Converts the value to the specified [Real] type, panics if the value cannot be represented by the target type.
+    /// Converts this value to the specified [`Real`] type, panics if the value cannot be represented by the target type.
     fn to_real_unchecked<R: Real>(self) -> R {
         R::from_f64(self.to_f64().unwrap()).unwrap()
     }
 
-    /// Multiplies the value by the specified `i32` coefficient. Panics if the coefficient cannot be converted into the target type.
+    /// Multiplies this value by the specified `i32` coefficient. Panics if the coefficient cannot be converted into the target type.
     fn times(self, n: i32) -> Self {
         self.mul(Self::from_i32(n).unwrap())
     }
@@ -51,10 +51,12 @@ pub trait Index:
 pub trait Real:
     RealField + FromPrimitive + ToPrimitive + Debug + Default + Pod + ThreadSafe
 {
+    /// Tries to convert this value to another [`Real`] type `T` by converting first to `f64` followed by `T::from_f64`. If the value cannot be represented by the target type, `None` is returned.
     fn try_convert<T: Real>(self) -> Option<T> {
         Some(T::from_f64(self.to_f64()?)?)
     }
 
+    /// Tries to convert the values of a statically sized `nalgebra::SVector` to another type, same behavior as [`Real::try_convert`]
     fn try_convert_vec_from<R, const D: usize>(vec: &SVector<R, D>) -> Option<SVector<Self, D>>
     where
         R: Real,
@@ -66,22 +68,22 @@ pub trait Real:
         Some(converted)
     }
 
-    /// Converts the value to the specified [Index] type. If the value cannot be represented by the target type, `None` is returned.
+    /// Converts this value to the specified [`Index`] type. If the value cannot be represented by the target type, `None` is returned.
     fn to_index<I: Index>(self) -> Option<I> {
         I::from_f64(self.to_f64()?)
     }
 
-    /// Converts the value to the specified [Index] type, panics if the value cannot be represented by the target type.
+    /// Converts this value to the specified [`Index`] type, panics if the value cannot be represented by the target type.
     fn to_index_unchecked<I: Index>(self) -> I {
         I::from_f64(self.to_f64().unwrap()).unwrap()
     }
 
-    /// Multiplies the value by the specified `i32` coefficient. Panics if the coefficient cannot be converted into the target type.
+    /// Multiplies this value by the specified `i32` coefficient. Panics if the coefficient cannot be converted into the target type.
     fn times(self, n: i32) -> Self {
         self.mul(Self::from_i32(n).unwrap())
     }
 
-    /// Multiplies the value by the specified `f64` coefficient. Panics if the coefficient cannot be converted into the target type.
+    /// Multiplies this value by the specified `f64` coefficient. Panics if the coefficient cannot be converted into the target type.
     fn times_f64(self, x: f64) -> Self {
         self.mul(Self::from_f64(x).unwrap())
     }

splashsurf_lib/src/workspace.rs

@@ -62,7 +62,7 @@ impl<I: Index, R: Real> Debug for ReconstructionWorkspace<I, R> {
     }
 }
 
-/// Workspace used by [crate::reconstruct_surface_inplace] internally to re-use allocated memory
+/// Workspace used by [`reconstruct_surface_inplace`] internally to re-use allocated memory
 pub(crate) struct LocalReconstructionWorkspace<I: Index, R: Real> {
     /// Storage for the particle positions (only used in octree based approach)
     pub particle_positions: Vec<Vector3<R>>,