[search] Documentation for search-v2 classes.

search/v2/features_layer_matcher.hpp

@@ -31,6 +31,21 @@ namespace search
 {
 namespace v2
 {
+// This class performs pairwise intersection between two layers of
+// features, where the first (child) layer is geographically smaller
+// than the second (parent) one.  It emits all pairs
+// (feature-from-child-layer, feature-from-parent-layer) of matching
+// features, where feature-from-child-layer belongs-to
+// feature-from-parent-layer.  Belongs-to is a partial relation on
+// features, and has different meaning for different search classes:
+//
+// * BUILDING belongs-to STREET iff the building is located on the street;
+// * BUILDING belongs-to CITY iff the building is located in the city;
+// * POI belongs-to BUILDING iff the poi is (roughly) located near or inside the building;
+// * STREET belongs-to CITY iff the street is (roughly) located in the city;
+// * etc.
+//
+// NOTE: this class *IS NOT* thread-safe.
 class FeaturesLayerMatcher
 {
 public:

search/v2/features_layer_path_finder.hpp

@@ -13,6 +13,15 @@ namespace v2
 {
 class FeaturesLayerMatcher;
 
+// This class is able to find all paths through a layered graph, with
+// vertices as features, and edges as pairs of vertices satisfying
+// belongs-to relation. For more details on belongs-to relation see
+// documentation for FeaturesLayerMatcher.
+//
+// In short, this class is able to find all features matching to a
+// given interpretation of a search query.
+//
+// NOTE: this class *IS* thread-safe.
 class FeaturesLayerPathFinder
 {
 public:

search/v2/street_vicinity_loader.hpp

@@ -19,6 +19,9 @@ class MwmValue;
 
 namespace search
 {
+// This class is able to load features in a street's vicinity.
+//
+// NOTE: this class *IS NOT* thread-safe.
 class StreetVicinityLoader
 {
 public:
@@ -40,7 +43,7 @@ public:
                        double offsetMeters);
 
   // Calls |fn| on each index in |sortedIds| where sortedIds[index]
-  // belongs so street's vicinity.
+  // belongs to the street's vicinity.
   template <typename TFn>
   void ForEachInVicinity(uint32_t streetId, vector<uint32_t> const & sortedIds, TFn const & fn)
   {
@@ -65,6 +68,14 @@ public:
     }
   }
 
+  // Calls |fn| on each feature belonging to the street's vicinity.
+  // Note that the distance from the feature to the street is
+  // calculated iff |filter| accepts the feature. This is a hacky
+  // solution and some kind of leaky abstraction. Probably we do not
+  // need this filter at all, but it allows us to early throw out all
+  // uninteresting features with complex geometry.
+  //
+  // TODO (@y, @m): fix this design.
   template <typename TFilter, typename TFn>
   void FilterFeaturesInVicinity(uint32_t streetId, TFilter && filter, TFn && fn)
   {