Documentation

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

indexer/feature.hpp

@@ -75,6 +75,18 @@ public:
   // (number of points in inner triangle-strips).
   using PointsBufferT = buffer_vector<m2::PointD, 32>;
 
+  /**
+   * @brief Retrieves the points of the feature.
+   *
+   * Depending on `scale`, the geometry may be simplified by reducing groups of nearby points to
+   * one point. If `scale` equals `FeatureType::BEST_GEOMETRY`, no such simplification takes place.
+   *
+   * Points are cached between calls and `scale` may not be honored if cached points are returned.
+   * To reliably enforce `scale`, call `ResetGemoetry()` immediately prior to `GetPoints()`.
+   *
+   * @param scale The map scale
+   * @return The points of the feature, simplified according to `scale`.
+   */
   PointsBufferT const & GetPoints(int scale);
   PointsBufferT const & GetTrianglesAsPoints(int scale);
 
@@ -82,6 +94,13 @@ public:
   FeatureID const & GetID() const { return m_id; }
 
   void ParseHeader2();
+
+  /**
+   * @brief Resets the geometry.
+   *
+   * This discards any cached points, resulting in points being re-fetched the next time
+   * `GetPoints()` or `GetTrianglesAsPoints()` is called.
+   */
   void ResetGeometry();
   void ParseGeometry(int scale);
   void ParseTriangles(int scale);

indexer/ftypes_matcher.hpp

@@ -624,20 +624,45 @@ double GetRadiusByPopulationForRouting(uint64_t p, LocalityType localityType);
 uint64_t GetPopulationByRadius(double r);
 //@}
 
-// Highway class. The order is important.
+/**
-// The enum values follow from the biggest roads (Trunk) to the smallest ones (Service).
+ * @brief Highway class.
+ *
+ * The order is important. The enum values follow from the biggest roads (Trunk) to the smallest ones (Service).
+ */
 enum class HighwayClass
 {
-  Undefined = 0,  // There has not been any attempt of calculating HighwayClass.
+  /**
+   * Used when there has not been any attempt of calculating HighwayClass.
+   */
+  Undefined = 0,
+  /**
+   * Motorway or trunk.
+   */
   Trunk,
   Primary,
   Secondary,
   Tertiary,
+  /**
+   * Unclassified, residential, living street and `highway=road`.
+   */
   LivingStreet,
+  /**
+   * Service, track, busway and `man_made=pier`.
+   */
   Service,
+  /**
+   * Anything not intended for motorized traffic: pedestrian, footway, bridleway, steps, cycleway,
+   * path and also `highway=construction`.
+   */
   Pedestrian,
-  Transported,    // Vehicles are transported by train or ferry.
+  /**
-  Count           // This value is used for internals only.
+   * Vehicles are transported by train or ferry.
+   */
+  Transported,
+  /**
+   * This value is used for internals only.
+   */
+  Count
 };
 
 std::string DebugPrint(HighwayClass const cls);

routing/road_point.hpp

@@ -10,7 +10,7 @@
 namespace routing
 {
 /**
- * @brief A unique identifier for any road point in an mwm file.
+ * @brief A unique identifier for any point on a road 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.
  */