From ab5e892bddeb9793179b0ca31c7106661dd486c2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Matt=C3=A9o=20Delabre?= <spam@delab.re>
Date: Sun, 16 May 2021 18:34:54 +0200
Subject: [PATCH] Improve simulation documentation

---
 src/tam/simulation.js | 52 ++++++++++++++++++++++---------------------
 1 file changed, 27 insertions(+), 25 deletions(-)

diff --git a/src/tam/simulation.js b/src/tam/simulation.js
index ba89988..7d985ac 100644
--- a/src/tam/simulation.js
+++ b/src/tam/simulation.js
@@ -8,16 +8,16 @@ import network from "./network.json";
 
 const server = "http://localhost:4321";
 
-// Number of milliseconds to stay at each stop
+// Time to stay at each stop (milliseconds)
 const stopTime = 10000;
 
-// Step used to compute the vehicle angle in meters
+// Step used to compute the vehicle bearing (meters)
 const angleStep = 10;
 
-// Maximum speed of a vehicle
+// Maximum speed of a vehicle (meters per millisecond)
 const maxSpeed = 60 / 3600;
 
-// Minimum speed of a vehicle
+// Minimum speed of a vehicle (meters per millisecond)
 const minSpeed = 10 / 3600;
 
 // Normal speed of a vehicle
@@ -38,42 +38,41 @@ class Course {
         // Stop to which this course is headed
         this.finalStop = null;
 
-        // Previous stops that this course left (with timestamps)
+        // Previous stops that this course left (stop id/timestamp pairs)
         this.prevPassings = [];
 
-        // Next stops that this course will leave (with timestamps)
+        // Next stops that this course will leave (stop id/timestamp pairs)
         this.nextPassings = [];
 
         // Stop that this course just left or will leave
         this.departureStop = null;
 
-        // Time at which the last stop was left or will be left
+        // Time at which the last stop was left or will be left (timestamp)
         this.departureTime = 0;
 
         // Next stop that this course will reach
-        // (if equal to departureStop, the course has reached its last stop)
         this.arrivalStop = null;
 
-        // Time at which the next stop will be left
+        // Time at which the next stop will be left (timestamp)
         this.arrivalTime = 0;
 
-        // Segment of points between the current departure and arrival
+        // Route between the current departure and arrival stops
         this.segment = null;
 
-        // Number of meters travelled between the two stops
+        // Distance already travelled between the two stops (meters)
         this.traveledDistance = 0;
 
-        // Current vehicle speed in meters per millisecond
+        // Current vehicle speed (meters per millisecond)
         this.speed = 0;
 
         // Current vehicle latitude and longitude
         this.position = [0, 0];
 
-        // Current vehicle bearing
+        // Current vehicle bearing (clockwise degrees from north)
         this.angle = 0;
     }
 
-    /** Retrieve information about the current segment used by the vehicle. */
+    /** Find a route between the current departure and arrival stops. */
     updateSegment() {
         if (this.departureStop === null || this.arrivalStop === null) {
             this.segment = null;
@@ -117,7 +116,7 @@ to ${this.arrivalStop}`);
         this.segment.properties.length = 1000 * turfLength(this.segment);
     }
 
-    /** Merge data received from the server. */
+    /** Merge passings data received from the server. */
     receiveData(data) {
         this.line = data.line;
         this.direction = data.direction;
@@ -129,7 +128,7 @@ to ${this.arrivalStop}`);
         );
 
         // Remove older passings from next passings
-        for (let [stop, time] of this.prevPassings) {
+        for (let [stop, _] of this.prevPassings) {
             delete passings[stop];
         }
 
@@ -268,6 +267,12 @@ to ${this.arrivalStop}`);
         this.position = positions[1];
     }
 
+    /**
+     * Compute the optimal speed to arrive on time.
+     * @param {number} distance Distance to cover (meters)
+     * @param {number} duration Remaining time (seconds)
+     * @return {number} Optimal speed (meters per second)
+     */
     static computeSpeed(distance, duration) {
         if (duration <= 0) {
             // Late: go to maximum speed
@@ -285,6 +290,7 @@ to ${this.arrivalStop}`);
     }
 }
 
+/** Fetch passing data from the server and update simulation. */
 const updateData = async courses => {
     const dataset = (await axios.get(`${server}/courses`)).data;
 
@@ -307,13 +313,6 @@ const updateData = async courses => {
     }
 };
 
-const tick = (courses, time) => {
-    for (const course of Object.values(courses)) {
-        course.update();
-        course.move(time);
-    }
-};
-
 export const start = () => {
     const courses = {};
     let lastFrame = null;
@@ -328,9 +327,12 @@ export const start = () => {
         }
 
         const time = lastFrame === null ? 0 : now - lastFrame;
-
         lastFrame = now;
-        tick(courses, time);
+
+        for (const course of Object.values(courses)) {
+            course.update();
+            course.move(time);
+        }
     };
 
     return { courses, update };