[traffic] Add documentation

Signed-off-by: mvglasow <michael -at- vonglasow.com>

map/traffic_manager.hpp

@@ -68,9 +68,27 @@ public:
   void SetStateListener(TrafficStateChangedFn const & onStateChangedFn);
 
   void SetDrapeEngine(ref_ptr<df::DrapeEngine> engine);
+  /**
+   * @brief Sets the version of the MWM used locally.
+   */
   void SetCurrentDataVersion(int64_t dataVersion);
 
+  /**
+   * @brief Enables or disables the traffic manager.
+   *
+   * This sets the internal state and notifies the drape engine. Enabling the traffic manager will
+   * invalidate its data, disabling it will notify the observer that traffic data has been cleared.
+   *
+   * Calling this function with `enabled` identical to the current state is a no-op.
+   *
+   * @param enabled True to enable, false to disable
+   */
   void SetEnabled(bool enabled);
+  /**
+   * @brief Whether the traffic manager is enabled.
+   *
+   * @return True if enabled, false if not
+   */
   bool IsEnabled() const;
 
   void UpdateViewport(ScreenBase const & screen);

traffic/speed_groups.hpp

@@ -5,6 +5,15 @@
 
 namespace traffic
 {
+/**
+ * A bucket for the ratio of the speed of moving traffic to the posted speed limit.
+ *
+ * Let Vmax be the posted speed limit and Vreal the speed at which traffic is currently flowing
+ * or expected to flow. The possible ratios (Vreal/Vmax) are grouped into buckets and, from then
+ * on, only the bucket number is used.
+ *
+ * The threshold ratios for the individual values are defined in `kSpeedGroupThresholdPercentage`.
+ */
 enum class SpeedGroup : uint8_t
 {
   G0 = 0,
@@ -20,24 +29,33 @@ enum class SpeedGroup : uint8_t
 
 static_assert(static_cast<uint8_t>(SpeedGroup::Count) <= 8, "");
 
-// Let M be the maximal speed that is possible on a free road
+/**
-// and let V be the maximal speed that is possible on this road when
+ * Threshold ratios for the individual values of `SpeedGroup`.
-// taking the traffic data into account.
+ *
-// We group all possible ratios (V/M) into a small number of
+ * Let Vmax be the posted speed limit and Vreal the speed at which traffic is currently flowing
-// buckets and only use the number of a bucket everywhere.
+ * or expected to flow. The possible ratios (Vreal/Vmax) are grouped into buckets and, from then
-// That is, we forget the specific values of V when transmitting and
+ * on, only the bucket number is used.
-// displaying traffic information. The value M of a road is known at the
+ *
-// stage of building the mwm containing this road.
+ * `kSpeedGroupThresholdPercentage[g]` is the maximum percentage of Vreal/Vmax for group g. Values
-//
+ * falling on the border of two groups may belong to either group.
-// kSpeedGroupThresholdPercentage[g] denotes the maximal value of (V/M)
+ *
-// that is possible for group |g|. Values falling on a border of two groups
+ * For special groups, where Vreal/Vmax is unknown or undefined, the threshold is 100%.
-// may belong to either group.
+ */
-//
-// The threshold percentage is defined to be 100 for the
-// special groups where V is unknown or not defined.
 extern uint32_t const kSpeedGroupThresholdPercentage[static_cast<size_t>(SpeedGroup::Count)];
 
-/// \note This method is used in traffic jam generation.
+/**
+ * Converts the ratio between speed of flowing traffic and the posted limit to a `SpeedGroup`.
+ *
+ * This method is used in traffic jam generation: Let Vmax be the posted speed limit and Vreal the
+ * speed at which traffic is currently flowing or expected to flow. The possible ratios
+ * (Vreal/Vmax) are grouped into buckets and, from then on, only the bucket number is used.
+ *
+ * This method performs the conversion from the ratio to a `SpeedGroup` bucket.
+ *
+ * @param p Vreal / Vmax * 100% (ratio expressed in percent)
+ *
+ * @return the `SpeedGroup` value which corresponds to `p`
+ */
 SpeedGroup GetSpeedGroupByPercentage(double p);
 
 std::string DebugPrint(SpeedGroup const & group);

traffic/traffic_info.hpp

@@ -15,8 +15,10 @@ class HttpClient;
 
 namespace traffic
 {
-// This class is responsible for providing the real-time
+/**
-// information about road traffic for one mwm file.
+ * @brief The `TrafficInfo` class is responsible for providing the real-time information about road
+ * traffic for one MWM.
+ */
 class TrafficInfo
 {
 public:
@@ -32,6 +34,16 @@ public:
     Unknown
   };
 
+  /**
+   * @brief The RoadSegmentId struct models a segment of a road.
+   *
+   * A road segment is the link between two consecutive points of an OSM way. The way must be
+   * tagged with a valid `highway` tag. A segment refers to a single direction.
+   *
+   * Therefore, an OSM way with `n` points has `n - 1` segments if tagged as one-way, `2 (n - 1)`
+   * otherwise (as each pair of adjacent points is connected by two segments, one in each
+   * direction.)
+   */
   struct RoadSegmentId
   {
     // m_dir can be kForwardDirection or kReverseDirection.
@@ -71,6 +83,9 @@ public:
     uint8_t m_dir : 1;
   };
 
+  /**
+   * @brief Mapping from feature segments to speed groups (see `speed_groups.hpp`), for one MWM.
+   */
   // todo(@m) unordered_map?
   using Coloring = std::map<RoadSegmentId, SpeedGroup>;
 
@@ -78,30 +93,62 @@ public:
 
   TrafficInfo(MwmSet::MwmId const & mwmId, int64_t currentDataVersion);
 
+  /**
+   * @brief Returns a `TrafficInfo` instance with pre-populated traffic information.
+   * @param coloring The traffic information (road segments and their speed group)
+   * @return The new `TrafficInfo` instance
+   */
   static TrafficInfo BuildForTesting(Coloring && coloring);
   void SetTrafficKeysForTesting(std::vector<RoadSegmentId> const & keys);
 
-  // Fetches the latest traffic data from the server and updates the coloring and ETag.
+  /**
-  // Construct the url by passing an MwmId.
+   * @brief Fetches the latest traffic data from the server and updates the coloring and ETag.
-  // The ETag or entity tag is part of HTTP, the protocol for the World Wide Web.
+   *
-  // It is one of several mechanisms that HTTP provides for web cache validation,
+   * The url is constructed using the `mwmId` specified in the constructor.
-  // which allows a client to make conditional requests.
+   *
-  // *NOTE* This method must not be called on the UI thread.
+   * The ETag or entity tag is part of HTTP, the protocol for the World Wide Web.
+   * It is one of several mechanisms that HTTP provides for web cache validation,
+   * which allows a client to make conditional requests.
+   *
+   * NOTE: This method must not be called on the UI thread.
+   *
+   * @param etag The entity tag
+   * @return True on success, false on failure.
+   */
   bool ReceiveTrafficData(std::string & etag);
 
-  // Returns the latest known speed group by a feature segment's id
+  /**
-  // or SpeedGroup::Unknown if there is no information about the segment.
+   * @brief Returns the latest known speed group by a feature segment's ID.
+   * @param id The road segment ID.
+   * @return The speed group, or `SpeedGroup::Unknown` if no information is available.
+   */
   SpeedGroup GetSpeedGroup(RoadSegmentId const & id) const;
 
   MwmSet::MwmId const & GetMwmId() const { return m_mwmId; }
   Coloring const & GetColoring() const { return m_coloring; }
   Availability GetAvailability() const { return m_availability; }
 
-  // Extracts RoadSegmentIds from mwm and stores them in a sorted order.
+  /**
+   * @brief Extracts RoadSegmentIds from an MWM and stores them in a sorted order.
+   * @param mwmPath Path to the MWM file
+   */
   static void ExtractTrafficKeys(std::string const & mwmPath, std::vector<RoadSegmentId> & result);
 
-  // Adds the unknown values to the partially known coloring map |knownColors|
+  /**
-  // so that the keys of the resulting map are exactly |keys|.
+   * @brief Adds unknown values to a partially known coloring map.
+   *
+   * After this method returns, the keys of `result` will be exactly `keys`. The speed group
+   * associated with each key will be the same as in `knownColors`, or `SpeedGroup::Unknown` for
+   * keys which are not found in `knownColors`.
+   *
+   * Keys in `knownColors` which are not in `keys` will be ignored.
+   *
+   * If `result` contains mappings prior to this method being called, they will be deleted.
+   *
+   * @param keys The keys for the result map.
+   * @param knownColors The map containing the updates.
+   * @param result The map to be updated.
+   */
   static void CombineColorings(std::vector<TrafficInfo::RoadSegmentId> const & keys,
                                TrafficInfo::Coloring const & knownColors,
                                TrafficInfo::Coloring & result);
@@ -143,13 +190,16 @@ private:
 
   ServerDataStatus ProcessFailure(platform::HttpClient const & request, int64_t const mwmVersion);
 
-  // The mapping from feature segments to speed groups (see speed_groups.hpp).
+  /**
+   * @brief The mapping from feature segments to speed groups (see speed_groups.hpp).
+   */
   Coloring m_coloring;
 
-  // The keys of the coloring map. The values are downloaded periodically
+  /**
-  // and combined with the keys to form m_coloring.
+   * @brief The keys of the coloring map. The values are downloaded periodically
-  // *NOTE* The values must be received in the exact same order that the
+   * and combined with the keys to form `m_coloring`.
-  // keys are saved in.
+   * *NOTE* The values must be received in the exact same order that the keys are saved in.
+   */
   std::vector<RoadSegmentId> m_keys;
 
   MwmSet::MwmId m_mwmId;