back: Document realtime data

back/data/realtime.js

@@ -1,19 +1,26 @@
 const tam = require('./sources/tam');
 const util = require('../util');
 
-/**
- * Fetch real-time information about courses in the TaM network.
- *
- * New data will only be fetched from the TaM server if necessary, otherwise
- * pulling from the in-memory cache.
- *
- * @return Mapping from active course IDs to current information about the
- * course, including its line number, next stop and next stop estimated
- * time of arrival (ETA).
- */
 let nextUpdate = null;
 let currentCourses = null;
 
+/**
+ * Fetch real-time information about active courses in the TaM network.
+ *
+ * New data will only be fetched from the TaM server once every minute,
+ * otherwise pulling from the in-memory cache.
+ *
+ * The following information is provided for each active course:
+ *
+ * - `id`: Unique identifier for the course.
+ * - `line`: Line number.
+ * - `nextStop`: Identifier of the next stop of the course.
+ * - `arrivalTime`: Timestamp at which the vehicle is predicted to arrive
+ *                  to the next stop.
+ * - `finalStop`: The final stop to which the course is headed.
+ *
+ * @return Mapping from active course IDs to information about each course.
+ */
 const getCourses = () => new Promise((res, rej) =>
 {
     if (nextUpdate !== null && Date.now() < nextUpdate)