Revert "WIP: Documentation"

This reverts commit d278794.

include/openPMD/ReadIterations.hpp

@@ -38,7 +38,7 @@ class LegacyIteratorAdaptor
  * This is a feature-restricted subset for the functionality of
  * `Series::snapshots()`, prefer using that. The compatibility layer is needed
  * due to the different value_type for `Series::readIterations()`-based
- * iteration (`IndexedIteration` instead of `std::pair<uint64_t, Iteration>`).
+ * iteration (`IterationIndex` instead of `std::pair<uint64_t, Iteration>`).
  *
  * Create instance via Series::readIterations().
  * For use in a C++11-style foreach loop over iterations.

include/openPMD/Series.hpp

@@ -708,8 +708,7 @@ class Series : public Attributable
      *
      * Conversely, the Access::CREATE and Access::APPEND access modes both
      * resolve to random-access by default, but can be specified to use
-     * Synchronous workflow if needed. A shorthand for Synchronous workflows can
-     * be found with Series::writeIterations().
+     * Synchronous workflow if needed.
      *
      * @param snapshot_workflow Specify the intended workflow
      *            in Access::CREATE and Access::APPEND. Leave unspecified in
@@ -737,9 +736,17 @@ class Series : public Attributable
     /**
      * @brief Entry point to the writing end of the streaming API.
      *
-     * Shorthand for `Series::snapshots()` for access types CREATE and APPEND
-     * called with parameter SnapshotWorkflow::Synchronous, i.e. for
-     * streaming-aware data producers.
+     * Creates and returns an instance of the WriteIterations class which is an
+     * intentionally restricted container of iterations that takes care of
+     * streaming semantics, e.g. ensuring that an iteration cannot be reopened
+     * once closed.
+     * For a less restrictive API in non-streaming situations,
+     * `Series::iterations` can be accessed directly.
+     * The created object is stored as member of the Series object, hence this
+     * method may be called as many times as a user wishes.
+     * There is only one shared iterator state per Series, even when calling
+     * this method twice.
+     * Look for the WriteIterations class for further documentation.
      *
      * @return WriteIterations
      */

src/Series.cpp

@@ -3188,15 +3188,14 @@ void Series::parseBase()
 
 WriteIterations Series::writeIterations()
 {
-    auto const access = IOHandler()->m_frontendAccess;
-    if (access != Access::CREATE && access != Access::APPEND)
+    auto &series = get();
+    if (series.m_deferred_initialization.has_value())
     {
-        throw error::WrongAPIUsage(
-            "[Series::writeIterations()] May only be applied for access modes "
-            "CREATE or APPEND. Use Series::snapshots() for random-access-type "
-            "or for read-type workflows.");
+        runDeferredInitialization();
     }
-    return snapshots(SnapshotWorkflow::Synchronous);
+    auto begin = make_writing_stateful_iterator(*this, series);
+    return Snapshots(std::shared_ptr<StatefulSnapshotsContainer>(
+        new StatefulSnapshotsContainer(std::move(begin))));
 }
 
 void Series::close()