diff --git a/map/traffic_manager.hpp b/map/traffic_manager.hpp index f2a2d28b1..f3169ccc9 100644 --- a/map/traffic_manager.hpp +++ b/map/traffic_manager.hpp @@ -68,9 +68,27 @@ public: void SetStateListener(TrafficStateChangedFn const & onStateChangedFn); void SetDrapeEngine(ref_ptr 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); diff --git a/traffic/speed_groups.hpp b/traffic/speed_groups.hpp index 385e68707..23c0da9ec 100644 --- a/traffic/speed_groups.hpp +++ b/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(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 -// taking the traffic data into account. -// We group all possible ratios (V/M) into a small number of -// buckets and only use the number of a bucket everywhere. -// That is, we forget the specific values of V when transmitting and -// displaying traffic information. The value M of a road is known at the -// stage of building the mwm containing this road. -// -// kSpeedGroupThresholdPercentage[g] denotes the maximal value of (V/M) -// that is possible for group |g|. Values falling on a border of two groups -// may belong to either group. -// -// The threshold percentage is defined to be 100 for the -// special groups where V is unknown or not defined. +/** + * Threshold ratios for the individual values of `SpeedGroup`. + * + * 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. + * + * `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. + * + * For special groups, where Vreal/Vmax is unknown or undefined, the threshold is 100%. + */ extern uint32_t const kSpeedGroupThresholdPercentage[static_cast(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); diff --git a/traffic/traffic_info.hpp b/traffic/traffic_info.hpp index c92378fc1..60e789986 100644 --- a/traffic/traffic_info.hpp +++ b/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; @@ -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 const & keys); - // Fetches the latest traffic data from the server and updates the coloring and ETag. - // Construct the url by passing an MwmId. - // 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. + /** + * @brief Fetches the latest traffic data from the server and updates the coloring and ETag. + * + * The url is constructed using the `mwmId` specified in the constructor. + * + * 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 & 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 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. - // *NOTE* The values must be received in the exact same order that the - // keys are saved in. + /** + * @brief The keys of the coloring map. The values are downloaded periodically + * and combined with the keys to form `m_coloring`. + * *NOTE* The values must be received in the exact same order that the keys are saved in. + */ std::vector m_keys; MwmSet::MwmId m_mwmId;