Document some functions

CHANGES.md

@@ -6,6 +6,8 @@
   * Fix a crash (uncaught json exception) when attempting to serialize a string that's
     invalid UTF-8, e.g. if long PS gets corrupted
   * Fix build when the installed version of nlohmann-json is too old (#113)
+  * Fix a couple of integer overflows, one affecting the subcarrier reset functionality
+    after 3.5 hours of runtime and another one after 41 days of constant data
 
 ## 1.0 (2024-06-27)
 

src/tmc/csv.h

@@ -16,8 +16,11 @@ struct CSVTable {
   std::vector<CSVRow> rows;
 };
 
+// Split a string into substrings by the delimiter character.
 std::vector<std::string> splitLine(const std::string& line, char delimiter);
 
+// Read a CSV table from a container of lines (e.g. vector of strings).
+/// \param delimiter Element delimiter that splits each line into columns.
 template <typename Container>
 std::vector<std::vector<std::string>> readCSVContainer(const Container& csvdata, char delimiter) {
   std::vector<std::vector<std::string>> lines;
@@ -28,9 +31,16 @@ std::vector<std::vector<std::string>> readCSVContainer(const Container& csvdata,
   return lines;
 }
 
+// Read a CSV table from a CSV file.
+/// \param delimiter Element delimiter that splits each line into columns.
 std::vector<std::vector<std::string>> readCSV(const std::string& filename, char delimiter);
+
+// Read a CSV table from a CSV file. The first line is treated as a title row.
+/// \param delimiter Element delimiter that splits each line into columns.
 CSVTable readCSVWithTitles(const std::string& filename, char delimiter);
 
+// Read a CSV table from a container of lines (e.g. vector of strings). The first line is treated as a title row.
+/// \param delimiter Element delimiter that splits each line into columns.
 template <typename Container>
 CSVTable readCSVContainerWithTitles(const Container& csvdata, char delimiter) {
   CSVTable table;
@@ -54,9 +64,16 @@ CSVTable readCSVContainerWithTitles(const Container& csvdata, char delimiter) {
   return table;
 }
 
+// Find an element by its title and return it as a string.
 std::string get_string(const CSVTable& table, const CSVRow& row, const std::string& title);
+
+// Find an element by its title and return it as int.
 int get_int(const CSVTable& table, const CSVRow& row, const std::string& title);
+
+// Find an element by its title and return it as uint16_t.
 uint16_t get_uint16(const CSVTable& table, const CSVRow& row, const std::string& title);
+
+// Find an element by its title and return it as bool.
 bool row_contains(const CSVTable& table, const CSVRow& row, const std::string& title);
 
 }  // namespace redsea

src/tmc/locationdb.h

@@ -66,6 +66,8 @@ struct LocationDatabase {
 std::ostream& operator<<(std::ostream& strm, const LocationDatabase& locdb);
 
 LocationDatabase loadLocationDatabase(const std::string& directory);
+
+// Read and return the location table number of a location database
 uint16_t readLTN(const std::string& directory);
 
 }  // namespace tmc

src/tmc/tmc.cc

@@ -421,6 +421,7 @@ void decodeLocation(const LocationDatabase& db, uint16_t ltn, nlohmann::ordered_
   }
 }
 
+// Does this event code match an actual TMC event?
 bool isValidEventCode(uint16_t code) {
   return g_event_data.find(code) != g_event_data.end();
 }
@@ -431,6 +432,7 @@ bool isValidSupplementaryCode(uint16_t code) {
 
 }  // namespace
 
+// Return a predefined TMC event by its code.
 Event getEvent(uint16_t code) {
   if (g_event_data.find(code) != g_event_data.end())
     return g_event_data.find(code)->second;