Postfix traversal, document visitHierarchy

Author: franzpoeschel

include/openPMD/Iteration.hpp

@@ -298,12 +298,7 @@ class Iteration
     [[deprecated("This attribute is no longer set by the openPMD-api.")]] bool
     closedByWriter() const;
 
-    void visitHierarchy(HierarchyVisitor &v) override
-    {
-        v(*this);
-        meshes.visitHierarchy(v);
-        particles.visitHierarchy(v);
-    }
+    void visitHierarchy(HierarchyVisitor &v) override;
 
     Meshes meshes{};
     Particles particles{};

include/openPMD/backend/Attributable.hpp

@@ -402,9 +402,27 @@ class Attributable
      */
     void touch();
 
-    virtual void visitHierarchy(HierarchyVisitor &);
+    /**
+     * Visitor pattern for the openPMD object hierarchy in postfix traversal.
+     *
+     * @note As the HierarchyVisitor interface can be tedious to implement,
+     *       consider using visitHierarchyFromLambda for a more convenient
+     *       interface.
+     *
+     * @param visitor Operations to run for each object.
+     */
+    virtual void visitHierarchy(HierarchyVisitor &visitor);
 
-    // definition inside include/openPMD/backend/HierarchyVisitorImpl.hpp
+    /**
+     * Visitor pattern for the openPMD object hierarchy in postfix traversal,
+     * lambda version.
+     *
+     * The lambda parameter will be called with a reference to each object in
+     * the current object's enclosed hierarchy.
+     *
+     * @note Definition inside include/openPMD/backend/HierarchyVisitorImpl.hpp.
+     * @param lambda Operations to run for each object.
+     */
     template <typename Lambda>
     void visitHierarchyFromLambda(Lambda &&lambda);
 

include/openPMD/backend/Container.hpp

@@ -266,11 +266,11 @@ class Container : virtual public Attributable
     template <typename ChildClass>
     void visitHierarchyImpl(HierarchyVisitor &v)
     {
-        v(*static_cast<ChildClass *>(this));
         for (auto &p : *this)
         {
             p.second.visitHierarchy(v);
         }
+        v(*static_cast<ChildClass *>(this));
     }
 
     // clang-format off

src/Iteration.cpp

@@ -254,6 +254,13 @@ bool Iteration::closedByWriter() const
     }
 }
 
+void Iteration::visitHierarchy(HierarchyVisitor &v)
+{
+    meshes.visitHierarchy(v);
+    particles.visitHierarchy(v);
+    v(*this);
+}
+
 void Iteration::flushFileBased(
     std::string const &filename,
     IterationIndex_t i,

src/Series.cpp

@@ -3571,8 +3571,8 @@ void Series::close()
 
 void Series::visitHierarchy(HierarchyVisitor &v)
 {
-    v(*this);
     get().iterations.visitHierarchy(v);
+    v(*this);
 }
 
 auto Series::currentSnapshot() -> std::optional<std::vector<IterationIndex_t>>