Added doc comments.

Author: horned-sphere

example_apps/transit/src/agents/agency.rs

@@ -37,16 +37,24 @@ use self::statistics::Statistics;
 
 mod statistics;
 
+/// Agency representing a transit agency (and its current state).
 #[derive(AgentLaneModel)]
 #[projections]
 #[agent(transient, convention = "camel")]
 pub struct AgencyAgent {
+    // Vehicles currently associated with the agency (keys are the IDs used by the service.).
     vehicles: MapLane<String, Vehicle>,
+    // Total count of vehicles associated with the agency.
     count: ValueLane<usize>,
+    // Average current speed of vehicles associated with the agency.
     speed: ValueLane<f64>,
+    // Update the vehicles associated with the agency.
     add_vehicles: CommandLane<Vec<VehicleResponse>>,
+    // Exposes the agency metadata.
     info: DemandLane<Agency>,
+    // Routes in the agency (keys are the IDs used by the service).
     routes: MapLane<String, Route>,
+    // Smallest geographical bounding box containing all vehicles associated with the agency.
     bounding_box: ValueLane<BoundingBox>,
 }
 
@@ -62,12 +70,16 @@ impl AgencyLifecycle {
     #[on_start]
     fn init(&self, context: HandlerContext<AgencyAgent>) -> impl EventHandler<AgencyAgent> + '_ {
         let this = self.clone();
+
+        //Fetch the titles of the routes for the agency and start polling for updates to its vehicles.
         let get_routes_and_poll = async move {
             let on_routes = this.clone().load_routes(context).await;
             let start_polling = this.start_polling(context);
             on_routes.followed_by(start_polling)
         };
         let state_uri = self.agency.state_uri();
+
+        //Associate this agency with the state that contains it.
         let add_to_state = context.send_command(
             None,
             state_uri,
@@ -111,6 +123,7 @@ impl AgencyLifecycle {
         vehicles: &[VehicleResponse],
     ) -> impl EventHandler<AgencyAgent> + '_ {
         let responses = vehicles.to_vec();
+        //Compute statistics for the new list of vehicles and update the state of all of the lanes.
         let stats = vehicles
             .iter()
             .fold(Statistics::default(), |s, v| s.update(v));

example_apps/transit/src/agents/country.rs

@@ -29,16 +29,24 @@ use crate::model::{agency::Agency, counts::Count};
 
 use super::join_value_logging_lifecycle;
 
+/// An agent with country level aggregate information.
 #[derive(AgentLaneModel)]
 #[projections]
 #[agent(transient, convention = "camel")]
 pub struct CountryAgent {
+    // Count of the number of vehicles within the country.
     count: ValueLane<Count>,
+    // Agencies in the country (keyed by service ID).
     agencies: MapLane<String, Agency>,
+    // The states within the country.
     states: MapLane<String, ()>,
+    // Counts of the number of vehicles within each state in the country.
     state_count: JoinValueLane<String, Count>,
+    // Average speed of all vehicles in the country.
     speed: ValueLane<f64>,
+    // Average speed of vehicles in each state in the country.
     state_speed: JoinValueLane<String, f64>,
+    // Add a new agency to the country.
     add_agency: CommandLane<Agency>,
 }
 

example_apps/transit/src/agents/state.rs

@@ -26,14 +26,20 @@ use crate::model::{agency::Agency, counts::Count};
 
 use super::join_value_logging_lifecycle;
 
+/// An agent with state level aggregate information.
 #[derive(AgentLaneModel)]
 #[projections]
 #[agent(transient, convention = "camel")]
 pub struct StateAgent {
+    // Count of the number of vehicles within the state.
     count: ValueLane<Count>,
+    // Counts of the number of vehicles within each agency in the state.
     agency_count: JoinValueLane<Agency, usize>,
+    // Average speed of vehicles within the state.
     speed: ValueLane<f64>,
+    // Average speeds of vehicles within each agency in the state.
     agency_speed: JoinValueLane<Agency, f64>,
+    // Add an agency to the state.
     add_agency: CommandLane<Agency>,
 }
 

example_apps/transit/src/agents/vehicle.rs

@@ -28,13 +28,18 @@ use tracing::{debug, info};
 
 use crate::model::vehicle::Vehicle;
 
+/// A agent representing the current state of a vehicle.
 #[derive(AgentLaneModel)]
 #[projections]
 #[agent(transient, convention = "camel")]
 pub struct VehicleAgent {
+    // Description of the vehicle.
     vehicle: ValueLane<Option<Vehicle>>,
+    // Speed history of the vehicle (keyed by arbitrary epoch milliseconds).
     speeds: MapLane<u64, u32>,
+    // Acceleration history of the vehicle (keyed by arbitrary epoch milliseconds).
     accelerations: MapLane<u64, u32>,
+    // Set the descriptor of the vehicle.
     add_vehicle: CommandLane<Vehicle>,
 }
 

example_apps/transit/src/lib.rs

@@ -78,6 +78,7 @@ pub fn create_plane(
     Ok(builder)
 }
 
+/// Starts the agents for each supported agency and then waits for the server to stop.
 pub async fn start_agencies_and_wait(
     agency_uris: Vec<RouteUri>,
     handle: ServerHandle,

example_apps/transit/src/ui.rs

@@ -34,6 +34,10 @@ impl UiConfig {
     }
 }
 
+/// Trivial web server to present the app UI.
+///
+/// #Arguments
+/// * `port` - The port that the swim server is listening on.
 pub fn ui_server_router(port: u16) -> Router {
     Router::new()
         .route("/index.html", get(index_html))

example_apps/transit/transit-model/src/model/agency.rs

@@ -23,6 +23,8 @@ use super::{
     vehicle::{Vehicle, VehicleResponse},
 };
 
+/// Representation of a transport agency. An agency is contained within a state, within a country. It will have
+/// some number of vehicles associated with it on some number of routes.
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Deserialize, Form, Hash)]
 #[form(tag = "agency")]
 pub struct Agency {
@@ -38,7 +40,7 @@ fn enc(s: &str) -> PercentEncode<'_> {
 }
 
 impl Agency {
-    
+    /// The Swim node URI of the agent that will represent this agency.
     pub fn uri(&self) -> String {
         format!(
             "/agency/{}/{}/{}",
@@ -48,14 +50,18 @@ impl Agency {
         )
     }
 
+    /// The Swim node URI of the country that contains this agency.
     pub fn country_uri(&self) -> String {
         format!("/country/{}", enc(&self.country))
     }
 
+    /// The Swim node URI of the state that contains this agency.
     pub fn state_uri(&self) -> String {
         format!("/state/{}/{}", enc(&self.country), enc(&self.state))
     }
 
+    /// Create a new vehicle entity from the response returned by the web service (incorporating information
+    /// from the route of the vehicle.)
     pub fn create_vehicle(&self, route: &Route, response: VehicleResponse) -> Vehicle {
         let VehicleResponse {
             id,

example_apps/transit/transit-model/src/model/bounding_box.rs

@@ -16,6 +16,7 @@ use std::fmt::Display;
 
 use swim::form::Form;
 
+/// A "square" geographical region described by intervals of latitude and longitude.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Form)]
 #[form(tag = "bounds", fields_convention = "camel")]
 pub struct BoundingBox {

example_apps/transit/transit-model/src/model/route.rs

@@ -18,15 +18,8 @@ use quick_xml::DeError;
 use serde::{Deserialize, Serialize};
 use swim::form::Form;
 
-#[derive(Deserialize, Serialize)]
-#[serde(rename = "body")]
-struct Body {
-    #[serde(rename = "@copyright")]
-    copyright: String,
-    #[serde(default)]
-    route: Vec<Route>,
-}
-
+/// A transit agency has some number of routes upon which are some number of vehicles. This type
+/// defines the mapping from the ID of a route to its descriptive title.
 #[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize, Form)]
 #[form(tag = "route")]
 pub struct Route {
@@ -36,6 +29,16 @@ pub struct Route {
     pub title: String,
 }
 
+#[derive(Deserialize, Serialize)]
+#[serde(rename = "body")]
+struct Body {
+    #[serde(rename = "@copyright")]
+    copyright: String,
+    #[serde(default)]
+    route: Vec<Route>,
+}
+
+/// Parse the routes for an agency from the XML returned by the corresponding service endpoint.
 pub fn load_xml_routes<R: BufRead>(read: R) -> Result<Vec<Route>, DeError> {
     quick_xml::de::from_reader::<R, Body>(read).map(|body| body.route)
 }
@@ -70,5 +73,4 @@ mod tests {
         let result = load_xml_routes(ROUTES_EXAMPLE).expect("Loading routes failed.");
         assert_eq!(result, expected);
     }
-
 }

example_apps/transit/transit-model/src/model/vehicle.rs

@@ -45,23 +45,37 @@ struct Body {
     last_time: Option<LastTime>,
 }
 
+/// The current state of a vehicle as reported by the web service.
 #[derive(Debug, Clone, PartialEq, Form)]
 #[form(tag = "vehicle", fields_convention = "camel")]
 pub struct Vehicle {
+    /// Unique service identifier for the vehicle.
     pub id: String,
+    /// The ID of the agency to which the vehicle belongs.
     pub agency: String,
+    /// The Swim node URI of the agent representing the vehicle.
     pub uri: String,
+    /// The service identifier of the route which the vehicle is on.
     pub route_tag: String,
+    /// ID defining the direction of the vehicle on its route.
     pub dir_id: String,
+    /// Last reported latitude of the vehicle.
     pub latitude: f64,
+    /// Last reported longitude of the vehicle.
     pub longitude: f64,
+    /// Last reported speed of the vehicle.
     pub speed: u32,
+    /// Number of seconds since the vehicle reported, relative to the timestamp of the response.
     pub secs_since_report: u32,
+    /// Last reported heading of the vehicle.
     pub heading: Heading,
+    /// Whether the future state of the vehicle can be predicted.
     pub predictable: bool,
+    /// Descriptive title of the route which the vehicle is on.
     pub route_title: String,
 }
 
+/// Representation of the type that is returned by the vehicles endpoint of the web servive.
 #[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Form)]
 pub struct VehicleResponse {
     #[serde(rename = "@id")]
@@ -91,6 +105,7 @@ pub struct LastTime {
     pub time: u64,
 }
 
+/// Parse the XML returned by the vehicles endpoint of the web service.
 pub fn load_xml_vehicles<R: BufRead>(
     read: R,
 ) -> Result<(Vec<VehicleResponse>, Option<u64>), DeError> {
@@ -101,6 +116,7 @@ pub fn load_xml_vehicles<R: BufRead>(
     )
 }
 
+/// Enumeration of cardinal and ordinal headings.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Tag)]
 pub enum Heading {
     N,
@@ -290,5 +306,4 @@ mod tests {
         assert_eq!(vehicles, expected);
         assert_eq!(time, Some(TIMESTAMP));
     }
-
 }