add code documentation

Author: louisgreiner

src/geometry_from_osm.rs

@@ -22,16 +22,17 @@ fn read_osm(input_file: &str, lrm_tag: &str) -> (Vec<osm4routing::Node>, Vec<osm
 
 #[derive(Parser, Debug)]
 #[command(version, about, long_about = None)]
+/// Arguments given by the command line interface.
 struct Args {
-    /// OpenStreetMap file to parse
+    /// OpenStreetMap file to parse.
     #[arg(short, long)]
     input_osm_file: String,
 
-    /// Output file where the LRS will be written
+    /// Output file where the [`Lrs`] will be written.
     #[arg(short, long)]
     output_lrs: String,
 
-    /// OpenStreetMap tag identifying the lrm. For the french railway network use ref:FR:SNCF_Reseau
+    /// OpenStreetMap tag identifying the LRM. The french railway network uses `ref:FR:SNCF_Reseau`.
     #[arg(short, long)]
     lrm_tag: String,
 }
@@ -40,7 +41,7 @@ fn main() {
     let cli_args = Args::parse();
     let (nodes, edges) = read_osm(&cli_args.input_osm_file, &cli_args.lrm_tag);
     println!(
-        "In OpenStreetMap, we have {} nodes and {} edges",
+        "In OpenStreetMap, we have {} nodes and {} edges.",
         nodes.len(),
         edges.len()
     );
@@ -93,7 +94,7 @@ fn main() {
         })
         .collect();
 
-    println!("In the LRS we have {} traversals", traversals.len());
+    println!("In the LRS, we have {} traversals.", traversals.len());
 
     let nodes: Vec<_> = nodes
         .iter()

src/lrs.rs

@@ -23,25 +23,25 @@ pub struct LrmHandle(usize);
 #[derive(Copy, Clone, Debug, Eq, Hash, PartialEq)]
 pub struct TraversalHandle(usize);
 
-/// Represents an Linear Reference Method (LRM)
-/// It is the combination of one (or more) [`Traversals`] for one [`LrmScale`]
+/// Represents an Linear Reference Method (LRM).
+/// It is the combination of one (or more) [`Traversal`]s for one [`LrmScale`].
 pub struct Lrm {
-    /// The scale of the LRM
+    /// The scale of this [`Lrm`].
     pub scale: LrmScale,
-    /// Traversal that is the reference of this LRM
+    /// The [`Traversal`] that is the reference of this [`Lrm`].
     pub reference_traversal: TraversalHandle,
-    /// All the traversals where this LRM applies
+    /// All the [`Traversal`]s where this [`Lrm`] applies.
     pub traversals: Vec<TraversalHandle>,
 }
 
-/// A traversal is path in the network that ends  [`Curve`]
-/// That traversals can be used for many different [`Lrm`]
+/// A [`Traversal`] is path in the network that ends [`Curve`].
+/// That [`Traversal`]s can be used for many different [`Lrm`]s.
 struct Traversal<CurveImpl: Curve> {
-    /// Identifies the traversal
+    /// Identifies this [`Traversal`].
     id: String,
-    /// The geometrical curve of the traversal
+    /// The geometrical [`Curve`] of this [`Traversal`].
     curve: CurveImpl,
-    /// All the [`Lrm`] that use this traversal
+    /// All the [`Lrm`]s that use this [`Traversal`].
     lrms: Vec<LrmHandle>,
 }
 
@@ -261,7 +261,7 @@ pub enum LrsError {
     InvalidArchive,
 }
 
-/// The basic functions to manipulate the LRS
+/// The basic functions to manipulate the [`Lrs`].
 pub trait LrsBase {
     /// Returns the [`LrmHandle`] (if it exists) of the [`Lrm`] identified by its `lrm_id`.
     fn get_lrm(&self, lrm_id: &str) -> Option<LrmHandle>;