v0.2.54..v0.2.55 changeset ElementIdsVisitor.h

diff --git a/hoot-core/src/main/cpp/hoot/core/visitors/ElementIdsVisitor.h b/hoot-core/src/main/cpp/hoot/core/visitors/ElementIdsVisitor.h
index a65a41e..a676939 100644
--- a/hoot-core/src/main/cpp/hoot/core/visitors/ElementIdsVisitor.h
+++ b/hoot-core/src/main/cpp/hoot/core/visitors/ElementIdsVisitor.h
@@ -36,6 +36,9 @@ namespace hoot
 
 /**
  * Used to get a collection of IDs for the elements that satisfy the specified criterion
+ *
+ * @todo Some of the utility methods may be redundant with related methods in WayUtils and TagUtils.
+ * Regardless, they should all be moved to other util classes that then call into this class.
  */
 class ElementIdsVisitor : public ConstElementVisitor
 {
@@ -43,27 +46,80 @@ public:
 
   static std::string className() { return "hoot::ElementIdsVisitor"; }
 
+  ElementIdsVisitor(const ElementType& elementType);
   ElementIdsVisitor(const ElementType& elementType, ElementCriterion* pCrit);
 
   void visit(const std::shared_ptr<const Element>& e) override;
 
-  // Get matching IDs
   std::vector<long> getIds() { return _elementIds; }
 
+  /**
+   * Retrieves the IDs of all elements of a given type
+   *
+   * @param map map owning the elements
+   * @param elementType type of element to retrieve
+   * @return a collection of numerical element IDs
+   */
+  static std::vector<long> findElements(const ConstOsmMapPtr& map, const ElementType& elementType);
+
+  /**
+   * Retrieves the IDs of all elements of a given type passing specified criteria
+   *
+   * @param map map owning the elements
+   * @param elementType type of element to retrieve
+   * @param pCrit criteria to satisfy
+   * @return a collection of numerical element IDs
+   */
   static std::vector<long> findElements(const ConstOsmMapPtr& map, const ElementType& elementType,
                                         ElementCriterion* pCrit);
 
+  /**
+   * Retrieves the IDs of nodes satifying specified criteria and within a radius of a specified
+   * location
+   *
+   * @param map map owning the elements
+   * @param pCrit criteria to satisfy
+   * @param refCoord the point out from which to search
+   * @param maxDistance the furthest distance away from the source point to search
+   * @return a collection of numerical node IDs
+   */
   static std::vector<long> findNodes(const ConstOsmMapPtr& map, ElementCriterion* pCrit,
                                      const geos::geom::Coordinate& refCoord, Meters maxDistance);
 
+  /**
+   * Retrieves the IDs of ways satifying specified criteria and within a radius of a specified
+   * location
+   *
+   * @param map map owning the elements
+   * @param pCrit criteria to satisfy
+   * @param refCoord the point out from which to search
+   * @param maxDistance the furthest distance away from the source point to search
+   * @param addError adds element circular error to the search radius
+   * @return a collection of numerical way IDs
+   */
   static std::vector<long> findWays(const ConstOsmMapPtr& map, ElementCriterion* pCrit,
                                     ConstWayPtr refWay, Meters maxDistance, bool addError);
 
-  // Convenience method for finding elements that contain the given tag
+  /**
+   * Retrieves the IDs of elements of a given type having a specified tag
+   *
+   * @param map map owning the elements
+   * @param elementType ype of element to retrieve
+   * @param key tag key
+   * @param value tag value
+   * @return a collection of numerical element IDs
+   */
   static std::vector<long> findElementsByTag(const ConstOsmMapPtr& map,
                                              const ElementType& elementType, const QString& key,
                                              const QString& value);
 
+  /**
+   * Retrieves the IDs of all ways owning a specified node
+   *
+   * @param map map owning the elements
+   * @param nodeId node ID to search for
+   * @return a collection of numerical way IDs
+   */
   static std::vector<long> findWaysByNode(const ConstOsmMapPtr& map, long nodeId);
 
   virtual QString getDescription() const { return "Collects the element IDs visited"; }
@@ -72,6 +128,8 @@ public:
 
 private:
 
+  // matching IDs; This should probably be a set, b/c there shouldn't be any dupe element IDs for
+  // the same element type in a map.
   std::vector<long> _elementIds;
   ElementType _elementType;
   ElementCriterion* _pCrit;