doc: add rustdoc for the exported functions

src/convert_file.rs

@@ -6,6 +6,24 @@ use crate::stations::{create_station_file, StationPoint};
 use anyhow::{Context, Result};
 use std::{collections::HashMap, sync::Mutex};
 
+/// Converts a given e57 file into a series of point clouds and station files.
+///
+/// This function reads an e57 file, extracts the point clouds, and saves them in multiples las files.
+/// It also creates station files from the point clouds, if you use potree.
+///
+/// # Parameters
+/// - `input_path`: The path to the e57 file that needs to be converted.
+/// - `output_path`: The destination (output dir) where the files will be saved.
+/// - `number_of_threads`: The number of threads to be used for parallel processing.
+///
+/// # Example
+/// ```
+/// use e57_to_las::convert_file;
+/// let input_path = String::from("path/to/input.e57");
+/// let output_path = String::from("path/to/output");
+/// let number_of_threads = 4;
+/// convert_file(input_path, output_path, number_of_threads);
+/// ```
 pub fn convert_file(
  input_path: String,
  output_path: String,
@@ -28,19 +46,20 @@ pub fn convert_file(
  pointclouds
  .par_iter()
  .enumerate()
- .for_each(|(index, pointcloud)| -> () {
+ .try_for_each(|(index, pointcloud)| -> Result<()> {
  println!("Saving pointcloud {}...", index);
- let converter_result =
- match convert_pointcloud(index, pointcloud, &input_path, &output_path) {
- Ok(r) => r,
- Err(e) => {
- eprintln!("Error encountered: {}", e);
- return;
- }
- };
-
- stations.lock().unwrap().extend(converter_result);
- });
+
+ let converter_result = convert_pointcloud(index, pointcloud, &input_path, &output_path)
+ .context(format!("Error while converting pointcloud {}", index))?;
+
+ stations
+ .lock()
+ .map_err(|_| anyhow::anyhow!("Failed to lock stations"))?
+ .extend(converter_result);
+
+ Ok(())
+ })
+ .context("Error during the parallel processing of pointclouds")?;
 
  create_station_file(output_path, stations)?;
 

src/convert_point.rs

@@ -1,5 +1,23 @@
 use e57::CartesianCoordinate;
 
+/// Converts an e57::Point to an optional las::Point.
+///
+/// This function takes an e57 point, extracts the Cartesian coordinates and optional color and intensity
+/// attributes, and constructs a corresponding las point.
+///
+/// # Parameters
+/// - `point`: The e57 point that needs to be converted.
+///
+/// # Returns
+/// - `Option<las::Point>`: An optional las point. The function returns `None` if the Cartesian coordinates
+/// are not valid. Otherwise, it returns a `Some(las::Point)` containing the converted point.
+///
+/// # Example
+/// ```ignore
+/// use e57_to_las::convert_point;
+/// let e57_point = e57::Point { };
+/// let las_point = convert_point(e57_point);
+/// ```
 pub fn convert_point(point: e57::Point) -> Option<las::Point> {
  let mut las_point = las::Point::default();
 

src/convert_pointcloud.rs

@@ -7,6 +7,32 @@ use e57::{E57Reader, PointCloud};
 use las::Write;
 use std::collections::HashMap;
 
+/// Converts a point cloud to a LAS file and returns a map of station points.
+///
+/// This function the points from the point cloud, converts them to LAS points using the `convert_point`
+/// function, and writes them to the LAS file.
+/// Additionally, it calculates the sum of coordinates and returns a hash map containing station
+/// points created with `create_station_point`.
+///
+/// # Parameters
+/// - `index`: The index of the point cloud.
+/// - `pointcloud`: A reference to the point cloud to be converted.
+/// - `input_path`: A reference to the input file path (E57 file).
+/// - `output_path`: A reference to the output dir.
+///
+/// # Returns
+/// - `Result<HashMap<usize, StationPoint>>`: A result containing a hash map that associates the index
+/// with a station point. Returns an error if any part of the conversion fails, including if there
+/// are no points in the point cloud.
+///
+/// # Example
+/// ```ignore
+/// use e57_to_las::convert_pointcloud;
+/// let pointcloud = e57::Pointcloud { };
+/// let input_path = String::from("path/to/input.e57");
+/// let output_path = String::from("path/to/output");
+/// convert_pointcloud(0, &pointcloud, input_path, output_path);
+/// ```
 pub fn convert_pointcloud(
  index: usize,
  pointcloud: &PointCloud,