diff --git a/indexer/mwm_set.hpp b/indexer/mwm_set.hpp index 4c649fae5..badc5ed58 100644 --- a/indexer/mwm_set.hpp +++ b/indexer/mwm_set.hpp @@ -141,8 +141,10 @@ public: explicit MwmSet(size_t cacheSize = 64) : m_cacheSize(cacheSize) {} virtual ~MwmSet() = default; - // Mwm handle, which is used to refer to mwm and prevent it from - // deletion when its FileContainer is used. + /** + * @brief Mwm handle, which is used to refer to mwm and prevent it from deletion when its + * FileContainer is used. + */ class MwmHandle { public: @@ -230,19 +232,26 @@ public: BadFile }; - // An Observer interface to MwmSet. Note that these functions can - // be called from *ANY* thread because most signals are sent when - // some thread releases its MwmHandle, so overrides must be as fast - // as possible and non-blocking when it's possible. + /** + * @brief An Observer interface to `MwmSet`. + * + * Note that these functions can be called from *ANY* thread because most signals are sent when + * some thread releases its MwmHandle, so overrides must be as fast as possible and non-blocking + * when it's possible. + */ class Observer { public: virtual ~Observer() = default; - // Called when a map is registered for the first time and can be used. + /** + * @brief Called when a map is registered for the first time and can be used. + */ virtual void OnMapRegistered(platform::LocalCountryFile const & /* localFile */) {} - // Called when a map is deregistered and can no longer be used. + /** + * @brief Called when a map is deregistered and can no longer be used. + */ virtual void OnMapDeregistered(platform::LocalCountryFile const & /* localFile */) {} }; @@ -290,7 +299,14 @@ public: /// @todo In fact, std::shared_ptr is a MwmId. Seems like better to make vector interface. void GetMwmsInfo(std::vector> & info) const; - // Clears caches and mwm's registry. All known mwms won't be marked as DEREGISTERED. + /** + * @brief Clears caches and mwm's registry. + * + * All known mwms won't be marked as DEREGISTERED. + * + * @todo what does “all won’t be marked” mean? Not all will be marked/some might not be marked? + * Or all will be unmarked? + */ void Clear(); void ClearCache(); @@ -334,10 +350,18 @@ private: ProcessEventList(events); } - // Sets |status| in |info|, adds corresponding event to |event|. + /** + * @brief Sets `status` in `info`, adds corresponding event to `event`. + * @param info + * @param status + * @param events + */ void SetStatus(MwmInfo & info, MwmInfo::Status status, EventList & events); - // Triggers observers on each event in |events|. + /** + * @brief Triggers observers on each event in `events`. + * @param events + */ void ProcessEventList(EventList & events); /// @precondition This function is always called under mutex m_lock. diff --git a/map/framework.hpp b/map/framework.hpp index c98d03490..341f5f69b 100644 --- a/map/framework.hpp +++ b/map/framework.hpp @@ -491,11 +491,18 @@ private: std::unique_ptr m_descriptionsLoader; public: - // Moves viewport to the search result and taps on it. + /** + * @brief Moves viewport to the search result and taps on it. + * @param res + * @param animation + */ void SelectSearchResult(search::Result const & res, bool animation); - // Cancels all searches, stops location follow and then selects - // search result. + /** + * @brief Cancels all searches, stops location follow and then selects search result. + * @param res + * @param animation + */ void ShowSearchResult(search::Result const & res, bool animation = true); size_t ShowSearchResults(search::Results const & results); diff --git a/platform/local_country_file.hpp b/platform/local_country_file.hpp index d384571c8..510b415c1 100644 --- a/platform/local_country_file.hpp +++ b/platform/local_country_file.hpp @@ -13,53 +13,88 @@ namespace platform { -// This class represents a path to disk files corresponding to some -// country region. -// -// This class also wraps World.mwm and WorldCoasts.mwm -// files from resource bundle, when they can't be found in a data -// directory. In this exceptional case, directory will be empty and -// SyncWithDisk()/DeleteFromDisk()/GetPath()/GetSize() will return -// incorrect results. -// -// In any case, when you're going to read a file LocalCountryFile points to, -// use platform::GetCountryReader(). +/** + * @brief Represents a path to disk files corresponding to some country region. + * + * This class also wraps World.mwm and WorldCoasts.mwm files from resource bundle, when they can't + * be found in a data directory. In this exceptional case, directory will be empty and + * `SyncWithDisk()`/`DeleteFromDisk()`/`GetPath()`/`GetSize()` will return incorrect results. + * + * In any case, when you're going to read a file LocalCountryFile points to, use + * `platform::GetCountryReader()`. + */ class LocalCountryFile { public: LocalCountryFile(); - // Creates an instance holding a path to countryFile's in a - // directory. Note that no disk operations are not performed until - // SyncWithDisk() is called. - // The directory must contain a full path to the country file. + /** + * @brief Creates an instance holding a path to countryFile's in a directory. + * + * Note that no disk operations are performed until `SyncWithDisk()` is called. + * + * @param directory full path to the country file + * @param countryFile + * @param version + */ LocalCountryFile(std::string directory, CountryFile countryFile, int64_t version); - // Syncs internal state like availability of files, their sizes etc. with disk. - // Generality speaking it's not always true. To know it for sure it's necessary to read a mwm in - // this method but it's not implemented by performance reasons. This check is done on - // building routes stage. + /** + * @brief Syncs internal state like availability of files, their sizes etc. with disk. + * + * Generality speaking it's not always true. To know it for sure it's necessary to read a mwm in + * this method but it's not implemented by performance reasons. This check is done on + * building routes stage. + */ void SyncWithDisk(); - // Removes specified file from disk if it is known for LocalCountryFile, i.e. - // it was found by a previous SyncWithDisk() call. + /** + * @brief Deletes a file from disk. + * + * Removes the specified file from disk for `LocalCountryFile`, if it is known, i.e. it was found + * by a previous SyncWithDisk() call. + * @param type + */ void DeleteFromDisk(MapFileType type) const; - // Returns path to a file. - // Return value may be empty until SyncWithDisk() is called. + /** + * @brief Returns the path to a file. + * + * Return value may be empty until SyncWithDisk() is called. + * + * @param type + * @return + */ std::string GetPath(MapFileType type) const; std::string GetFileName(MapFileType type) const; - // Returns size of a file. - // Return value may be zero until SyncWithDisk() is called. + /** + * @brief Returns the size of a file. + * + * Return value may be zero until SyncWithDisk() is called. + * + * @param type + * @return + */ uint64_t GetSize(MapFileType type) const; - // Returns true when some files are found during SyncWithDisk. - // Return value is false until SyncWithDisk() is called. + /** + * @brief Returns true when files are found during `SyncWithDisk()`. + * + * Return value is false until `SyncWithDisk()` is called. + * + * @return + */ bool HasFiles() const; - // Checks whether files specified in filesMask are on disk. - // Return value will be false until SyncWithDisk() is called. + /** + * @brief Checks whether files specified in filesMask are on disk. + * + * Return value will be false until SyncWithDisk() is called. + * + * @param type + * @return + */ bool OnDisk(MapFileType type) const; bool IsInBundle() const { return m_directory.empty(); } @@ -74,8 +109,17 @@ public: bool ValidateIntegrity() const; - // Creates LocalCountryFile for test purposes, for a country region - // with countryFileName (without any extensions). Automatically performs sync with disk. + // + /** + * @brief Creates a `LocalCountryFile` for test purposes. + * + * Creates a `LocalCountryFile` for test purposes, for a country region with `countryFileName`. + * Automatically performs sync with disk. + * + * @param countryFileName The filename, without any extension. + * @param version The data version. + * @return + */ static LocalCountryFile MakeForTesting(std::string countryFileName, int64_t version = 0); // Used in generator only to simplify getting instance from path. diff --git a/routing/road_point.hpp b/routing/road_point.hpp index 346681a68..ddf053eeb 100644 --- a/routing/road_point.hpp +++ b/routing/road_point.hpp @@ -9,10 +9,11 @@ namespace routing { -// RoadPoint is a unique identifier for any road point in mwm file. -// -// Contains feature id and point id. -// Point id is the ordinal number of the point in the road. +/** + * @brief A unique identifier for any road point in an mwm file. + * + * It contains a feature id and point id. The point id is the ordinal number of the point in the road. + */ class RoadPoint final { public: diff --git a/routing/segment.hpp b/routing/segment.hpp index b10e25b92..ed886576e 100644 --- a/routing/segment.hpp +++ b/routing/segment.hpp @@ -9,14 +9,16 @@ namespace routing { -// This is directed road segment used as vertex in index graph. -// -// You can imagine the segment as a material arrow. -// Head of each arrow is connected to fletchings of next arrows with invisible links: -// these are the edges of the graph. -// -// Position of the segment is a position of the arrowhead: GetPointId(true). -// This position is used in heuristic and edges weight calculations. +/** + * @brief A directed road segment used as a vertex in the index graph. + * + * You can imagine the segment as a material arrow. + * Head of each arrow is connected to fletchings of next arrows with invisible links: + * these are the edges of the graph. + * + * Position of the segment is a position of the arrowhead: GetPointId(true). + * This position is used in heuristic and edges weight calculations. + */ class Segment final { public: @@ -82,7 +84,9 @@ public: bool operator<(SegmentEdge const & edge) const; private: - // Target is vertex going to for outgoing edges, vertex going from for ingoing edges. + /** + * @brief Vertex going to for outgoing edges, vertex going from for ingoing edges. + */ Segment m_target; RouteWeight m_weight; }; diff --git a/routing_common/num_mwm_id.hpp b/routing_common/num_mwm_id.hpp index 3852be217..5212e268e 100644 --- a/routing_common/num_mwm_id.hpp +++ b/routing_common/num_mwm_id.hpp @@ -17,11 +17,21 @@ using NumMwmId = std::uint16_t; NumMwmId constexpr kFakeNumMwmId = std::numeric_limits::max(); NumMwmId constexpr kGeneratorMwmId = 0; +/** + * @brief A numbered list of country files. + */ class NumMwmIds final { public: bool IsEmpty() const { return m_idToFile.empty(); } + /** + * @brief Registers a file, i.e. adds it to the instance. + * + * If the instance already contains the file, this is a no-op. + * + * @param file + */ void RegisterFile(platform::CountryFile const & file) { if (ContainsFile(file)) @@ -34,22 +44,42 @@ public: //LOG(LDEBUG, ("MWM:", file.GetName(), "=", id)); } + /** + * @brief Whether this instance contains a given file. + * @param file + * @return + */ bool ContainsFile(platform::CountryFile const & file) const { return m_fileToId.find(file) != m_fileToId.cend(); } + /** + * @brief Whether this instance contains a file at a given index. + * @param mwmId The index. + * @return + */ bool ContainsFileForMwm(NumMwmId mwmId) const { return mwmId < m_idToFile.size(); } + /** + * @brief Returns a file by index. + * @param mwmId The index. + * @return + */ platform::CountryFile const & GetFile(NumMwmId mwmId) const { ASSERT_LESS(mwmId, m_idToFile.size(), ()); return m_idToFile[mwmId]; } + /** + * @brief Returns the index for a given file. + * @param file + * @return + */ NumMwmId GetId(platform::CountryFile const & file) const { auto const it = m_fileToId.find(file);