add more comments to the GeoHandler

DDCore/include/DD4hep/GeoHandler.h

@@ -88,8 +88,12 @@ namespace dd4hep {
 
     protected:
       bool  m_propagateRegions { false };
+
+      /// actual container with std::vector (preserves order)
       std::map<int, std::vector<const TGeoNode*> >*    m_data      { nullptr };
+      /// redundant container with std::set (for lookup purpose)
       std::map<int, std::set<const TGeoNode*> >* m_set_data { nullptr };
+
       std::map<const TGeoNode*, std::vector<TGeoNode*> >* m_daughters { nullptr };
       /// Internal helper to collect geometry information from traversal
       GeoHandler& i_collect(const TGeoNode* parent,

DDCore/src/GeoHandler.cpp

@@ -78,9 +78,13 @@ detail::GeoHandler::~GeoHandler() {
 }
 
 std::map<int, std::vector<const TGeoNode*> >* detail::GeoHandler::release() {
+  /// release the std::vector geometry container (preserves order)
   std::map<int, std::vector<const TGeoNode*> >* d = m_data;
   m_data = nullptr;
 
+  /// the std::set container (for lookup purpose) is not needed anymore, so delete it
+  /// the container is always present since the call of the constructor
+  /// we never expect to call release() twice (will release nullptr)
   delete m_set_data;
   m_set_data = nullptr;
 
@@ -162,6 +166,7 @@ detail::GeoHandler& detail::GeoHandler::i_collect(const TGeoNode* /* parent */,
     }
   }
   /// Collect the hierarchy of placements
+  /// perform lookup using std::set::emplace (faster than std::find for the large number of geometries)
   if ( (*m_set_data)[level].emplace(current).second ) {
     (*m_data)[level].push_back(current);
   }