Doc improvements

Author: Tristramg

schema/lrs.fbs

@@ -119,7 +119,7 @@ table LinearReferencingMethod {
     properties:[Property];
 
     traversal_index:TraversalRef;
-    /// An LRM can apply to multiple referals
+    /// An LRM can apply to multiple traversal
     /// For instance a LRM can be the central line of a highway
     /// And that LRM is the reference for the two other traversals corresponding to each direction
     used_on:[TraversalRef];

src/geometry_from_osm.rs

@@ -22,34 +22,35 @@ 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,
 }
 
-// When sortir the edges, we test each candidate to see if they match and if they need to bee reversed
+// When sorting the edges, each candidate is tested to see if they match and if they need to be reversed.
 #[derive(PartialEq, Eq, Debug)]
 enum Candidate {
     Source,
     Target,
     NotCandidate,
 }
 
-// If we have a string of edges that ends with `end_edge`
-// Can the candidate Edge(s, t) be joined at the end_edge(source, target)
-// Returns Forward if the Edge’s can be appened in the same direction (target == s)
-// Backward if it must be reverded (target == t)
-// And NotCandidate if it can’t be appended
-// consider_source means that we consider the source (or target if false) of the last_edge
+// If we have a string of edges that ends with `end_edge`,
+// the candidate `Edge(s, t)` can be joined at the `end_edge(source, target)`.
+// Returns Forward if the `Edge` can be append in the same direction `(target == s)`,
+// Backward if it must be reversed `(target == t)` or
+// And NotCandidate if it can’t be appended.
+// `consider_source` means that the source (or target if false) of the `last_edge` is considered.
 fn can_be_appended(candidate: &Edge, last_edge: &Edge, consider_source: bool) -> Candidate {
     let last_node = if consider_source {
         last_edge.source
@@ -136,6 +137,9 @@ fn sort_edges(edges: Vec<Edge>, traversal_ref: &str) -> Vec<(Edge, bool)> {
     return sorted;
 }
 
+/// Example: to generate an LRS from an OpenStreetMap dump
+/// 
+/// `$ cargo run --release --bin geometry_from_osm -- -i france.osm.pbf  -o osm_83000.lrs.bin --lrm-tag=ref:fr:SNCF_Reseau`
 fn main() {
     let cli_args = Args::parse();
     let (nodes, edges) = read_osm(&cli_args.input_osm_file, &cli_args.lrm_tag);
@@ -209,7 +213,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()
@@ -275,6 +279,7 @@ fn main() {
         views: Some(fbb.create_vector(&[view])),
         ..Default::default()
     };
+
     let lrs = Lrs::create(&mut fbb, &lrs_args);
 
     fbb.finish(lrs, None);

src/lrs.rs

@@ -23,15 +23,25 @@ pub struct LrmHandle(usize);
 #[derive(Copy, Clone, Debug, Eq, Hash, PartialEq)]
 pub struct TraversalHandle(usize);
 
-struct Lrm {
-    scale: LrmScale,
-    reference_traversal: TraversalHandle,
-    traversals: Vec<TraversalHandle>,
+/// 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 this [`Lrm`].
+    pub scale: LrmScale,
+    /// The [`Traversal`] that is the reference of this [`Lrm`].
+    pub reference_traversal: TraversalHandle,
+    /// All the [`Traversal`]s where this [`Lrm`] applies.
+    pub traversals: Vec<TraversalHandle>,
 }
 
+/// 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 this [`Traversal`].
     id: String,
+    /// The geometrical [`Curve`] of this [`Traversal`].
     curve: CurveImpl,
+    /// All the [`Lrm`]s that use this [`Traversal`].
     lrms: Vec<LrmHandle>,
 }
 
@@ -251,7 +261,8 @@ pub enum LrsError {
     InvalidArchive,
 }
 
-trait LrsBase {
+/// 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>;
     /// Returns the [`TraversalHandle`] (if it exists) of the [`Traversal`] identified by its `traversal_id`.

src/lrs_generated.rs

@@ -1974,7 +1974,7 @@ impl<'a> LinearReferencingMethod<'a> {
     // which contains a valid value in this slot
     unsafe { self._tab.get::<TraversalRef>(LinearReferencingMethod::VT_TRAVERSAL_INDEX, None)}
   }
-  /// An LRM can apply to multiple referals
+  /// An LRM can apply to multiple traversal
   /// For instance a LRM can be the central line of a highway
   /// And that LRM is the reference for the two other traversals corresponding to each direction
   #[inline]