added a whole ton of doc string improvements

rust/altrios-core/src/lin_search_hint.rs

@@ -1,6 +1,7 @@
 use crate::imports::*;
 use crate::si;
 
+// Per Geordie, we could probably get rid of this `DirT` code
 pub type DirT = u8;
 
 #[allow(non_snake_case)]
@@ -14,11 +15,17 @@ pub mod Dir {
     pub const Bwd: DirT = 2;
 }
 
+/// Has method that returns offset from start of PathTpc
 pub trait GetOffset {
+    /// Returns offset from start of PathTpc
     fn get_offset(&self) -> si::Length;
 }
 
+/// Contains method to calculate the index immediately before `offset` given the previous calculated
+/// index, `idx`, and a direction `DirT`.
 pub trait LinSearchHint {
+    /// Calculate the index immediately before `offset` given the previous calculated index, `idx`,
+    /// and a direction `DirT`.
     fn calc_idx<const DIR: DirT>(&self, offset: si::Length, idx: usize) -> anyhow::Result<usize>;
 }
 

rust/altrios-core/src/track/path_track/link_point.rs

@@ -1,24 +1,28 @@
 use super::super::LinkIdx;
 use crate::imports::*;
 
-/// Specifies the relative start of a link within the `PathTpc`
+/// Point along PathTpc representing the start of a link and the number of grade, curve, and cat
+/// power limit points contained within the same link,`link_idx`, in the PathTpc.
+///
+/// Note that for the `*_count` fields, these represent points contained in the link for which grade,
+/// curve, ... information is known, not including the final point in the link.
 #[derive(Debug, Default, Clone, Copy, Serialize, Deserialize, PartialEq, PartialOrd, SerdeAPI)]
 #[altrios_api]
 pub struct LinkPoint {
-    /// TODO: Geordie, doc string.  What does offset mean here?  distance from start of link to front
-    /// of train?  Something else?
+    /// Distance relative to the start of the PathTpc where `link_idx` starts
     #[api(skip_set)]
     pub offset: si::Length,
     #[api(skip_set)]
-    /// TODO: Geordie, doc string.
+    /// Number of grade points in the current link
     pub grade_count: usize,
     #[api(skip_set)]
-    /// TODO: Geordie, doc string.
+    /// Number of curve points in the current link
     pub curve_count: usize,
     #[api(skip_set)]
-    /// TODO: Geordie, doc string.
+    /// Number of catenary power limit points in the current link
     pub cat_power_count: usize,
     #[api(skip_set)]
+    /// [LinkIdx] of current link
     pub link_idx: LinkIdx,
 }
 

rust/altrios-core/src/track/path_track/path_res_coeff.rs

@@ -1,22 +1,23 @@
 use crate::imports::*;
 
-/// Struct containing linear resistance coefficients for a particular offset w.r.t. `PathTpc`
-#[derive(Clone, Copy, Default, Debug, PartialEq, PartialOrd, Serialize, Deserialize, SerdeAPI)]
 #[altrios_api]
-/// TODO: Geordie, doc string.
+#[derive(Clone, Copy, Default, Debug, PartialEq, PartialOrd, Serialize, Deserialize, SerdeAPI)]
+/// Struct containing linear resistance coefficients for a particular offset with respect to start
+/// of `PathTpc`
 pub struct PathResCoeff {
     #[api(skip_set)]
-    /// TODO: Geordie, doc string.
+    /// Distance from start of `PathTpc`
     pub offset: si::Length,
     #[api(skip_set)]
-    /// TODO: Geordie, doc string.
+    /// Non-dimensional grade/curve resistance.  
     pub res_coeff: si::Ratio,
     #[api(skip_set)]
-    /// TODO: Geordie, doc string.
+    /// Cumulative sum of `res_coeff` times length up to this `PathResCoeff` along `PathTpc`
     pub res_net: si::Length,
 }
 
 impl PathResCoeff {
+    /// Cumulative sum of `res_coeff` times length up to this `offset` along `PathTpc`
     pub fn calc_res_val(&self, offset: si::Length) -> si::Length {
         self.res_net + self.res_coeff * (offset - self.offset)
     }

rust/altrios-core/src/track/path_track/path_tpc.rs

@@ -6,7 +6,9 @@ use super::train_params::*;
 use crate::imports::*;
 
 // TODO: make PathTpc robust to `Vec<LinkPoint>` that ends with `0`
-/// Train resistance
+/// Vector data used to represent track-dependent train performance parameters along the path the
+/// train will follow.  This contains all the positionally important data for the train resistance
+/// model.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, SerdeAPI)]
 #[altrios_api]
 pub struct PathTpc {