From 185febd8d8cdd598785d8fd7fa8e23846922d5c0 Mon Sep 17 00:00:00 2001
From: mvglasow <michael -at- vonglasow.com>
Date: Sat, 31 May 2025 21:21:31 +0300
Subject: [PATCH] [traffic] Documentation and comments

Signed-off-by: mvglasow <michael -at- vonglasow.com>
---
 map/traffic_manager.cpp |  7 -------
 map/traffic_manager.hpp | 43 ++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 42 insertions(+), 8 deletions(-)

diff --git a/map/traffic_manager.cpp b/map/traffic_manager.cpp
index 6d1dde719..f6e41767e 100644
--- a/map/traffic_manager.cpp
+++ b/map/traffic_manager.cpp
@@ -449,13 +449,6 @@ void TrafficManager::DecodeFirstMessage()
       m_feedQueue.erase(m_feedQueue.begin());
   }
 
-/*
- * TODO this breaks things in the current test setup.
- * When TrafficManager starts up and processes the first feed, maps are not loaded yet and messages
- * cannot be decoded, so they are added to the cache without segments.
- * The next feed (being a static file) returns the same data, so this check causes the message to
- * get ignored as it has not changed.
- */
   // check if message is actually newer
   auto it = m_messageCache.find(message.m_id);
   bool process = (it == m_messageCache.end());
diff --git a/map/traffic_manager.hpp b/map/traffic_manager.hpp
index dfea2b0b1..c8f8967bf 100644
--- a/map/traffic_manager.hpp
+++ b/map/traffic_manager.hpp
@@ -106,6 +106,7 @@ public:
    * @param enabled True to enable, false to disable
    */
   void SetEnabled(bool enabled);
+
   /**
    * @brief Whether the traffic manager is enabled.
    *
@@ -124,7 +125,7 @@ public:
    *
    * @todo Currently, all MWMs must be loaded before calling `Start()`, as MWMs loaded after that
    * will not get picked up. We need to extend `TrafficManager` to react to MWMs being added (and
-   * removed) – note that this affects the data source, not the set of active MWMs.
+   * removed) – note that this affects the `DataSource`, not the set of active MWMs.
    *
    * @todo Start is currently not integrated with state or pause/resume logic (all of which might
    * not be fully implemented ATM). If the traffic manager is not started, no message processing
@@ -136,6 +137,16 @@ public:
   void UpdateViewport(ScreenBase const & screen);
   void UpdateMyPosition(MyPosition const & myPosition);
 
+  /**
+   * @brief Invalidates traffic information.
+   *
+   * Invalidating causes traffic data to be re-requested.
+   *
+   * This happens when a new MWM file is downloaded, the traffic manager is enabled after being
+   * disabled or resumed after being paused.
+   *
+   * @todo this goes for the old MWM arch, see if this makes sense for TraFF.
+   */
   void Invalidate();
 
   void OnDestroySurface();
@@ -388,7 +399,37 @@ private:
    */
   void RequestTrafficData(MwmSet::MwmId const & mwmId, bool force);
 
+  /**
+   * @brief Clears the entire traffic cache.
+   *
+   * This is currently called when the traffic manager is enabled or disabled.
+   *
+   * The old MWM traffic architecture was somewhat liberal in clearing its cache and re-fetching
+   * traffic data. This was possible because data was pre-processed and required no processing
+   * beyond deserialization, whereas TraFF data is more expensive to recreate. Also, the old
+   * architecture lacked any explicit notion of expiration; the app decided that data was to be
+   * considered stale after a certain period of time. TraFF, in contrast, has an explicit expiration
+   * time for each message, which can be anywhere from a few minutes to several weeks or months.
+   * Messages that have expired get deleted individually.
+   * For this reason, the TraFF message cache should not be cleared out under normal conditions
+   * (the main exception being tests).
+   *
+   * @todo Currently not implemented for TraFF; implement it for test purposes but do not call when
+   * the enabled state changes.
+   */
   void Clear();
+
+  /**
+   * @brief Removes traffic data for one specific MWM from the cache.
+   *
+   * This would be used when an MWM file gets deregistered and its traffic data is no longer needed.
+   * With the old MWM traffic architecture (pre-processed sets of segments), this method was also
+   * used to shrink the cache to stay below a certain size (no longer possible with TraFF, due to
+   * the data structures being more complex, and also due to re-fetching data being expensive in
+   * terms of computing time).
+   *
+   * @param mwmId The mwmId for which to remove traffic data.
+   */
   void ClearCache(MwmSet::MwmId const & mwmId);
 // TODO no longer needed
 #ifdef traffic_dead_code