Documentation

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

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
+   * @brief An Observer interface to `MwmSet`.
-  // some thread releases its MwmHandle, so overrides must be as fast
+   *
-  // as possible and non-blocking when it's possible.
+   * 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<MwmInfo> is a MwmId. Seems like better to make vector<MwmId> interface.
   void GetMwmsInfo(std::vector<std::shared_ptr<MwmInfo>> & 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.

map/framework.hpp

@@ -491,11 +491,18 @@ private:
   std::unique_ptr<descriptions::Loader> 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);

platform/local_country_file.hpp

@@ -13,53 +13,88 @@
 
 namespace platform
 {
-// This class represents a path to disk files corresponding to some
+/**
-// country region.
+ * @brief Represents a path to disk files corresponding to some country region.
-//
+ *
-// This class also wraps World.mwm and WorldCoasts.mwm
+ * This class also wraps World.mwm and WorldCoasts.mwm files from resource bundle, when they can't
-// files from resource bundle, when they can't be found in a data
+ * be found in a data directory. In this exceptional case, directory will be empty and
-// directory. In this exceptional case, directory will be empty and
+ * `SyncWithDisk()`/`DeleteFromDisk()`/`GetPath()`/`GetSize()` will return incorrect results.
-// 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()`.
-// 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
+   * @brief Creates an instance holding a path to countryFile's in a directory.
-  // SyncWithDisk() is called.
+   *
-  // The directory must contain a full path to the country file.
+   * 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
+   * @brief Syncs internal state like availability of files, their sizes etc. with disk.
-  // this method but it's not implemented by performance reasons. This check is done on
+   *
-  // building routes stage.
+   * 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.

routing/road_point.hpp

@@ -9,10 +9,11 @@
 
 namespace routing
 {
-// RoadPoint is a unique identifier for any road point in mwm file.
+/**
-//
+ * @brief A unique identifier for any road point in an mwm file.
-// Contains feature id and point id.
+ *
-// Point id is the ordinal number of the point in the road.
+ * 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:

routing/segment.hpp

@@ -9,14 +9,16 @@
 
 namespace routing
 {
-// This is directed road segment used as vertex in index graph.
+/**
-//
+ * @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:
+ * You can imagine the segment as a material arrow.
-// these are the edges of the graph.
+ * 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.
+ * 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;
 };

routing_common/num_mwm_id.hpp

@@ -17,11 +17,21 @@ using NumMwmId = std::uint16_t;
 NumMwmId constexpr kFakeNumMwmId = std::numeric_limits<NumMwmId>::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);