From a73c4c67284b44a9ca29a8ad0724b86ccd5ced1f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Franz=20P=C3=B6schel?= <franz.poeschel@gmail.com>
Date: Tue, 29 Oct 2024 12:57:26 +0100
Subject: [PATCH] WIP: Documentation

---
 include/openPMD/ReadIterations.hpp |  2 +-
 include/openPMD/Series.hpp         | 17 +++++------------
 src/Series.cpp                     | 13 +++++++------
 3 files changed, 13 insertions(+), 19 deletions(-)

diff --git a/include/openPMD/ReadIterations.hpp b/include/openPMD/ReadIterations.hpp
index d393d99706..9a4eff9221 100644
--- a/include/openPMD/ReadIterations.hpp
+++ b/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 (`IterationIndex` instead of `std::pair<uint64_t, Iteration>`).
+ * iteration (`IndexedIteration` instead of `std::pair<uint64_t, Iteration>`).
  *
  * Create instance via Series::readIterations().
  * For use in a C++11-style foreach loop over iterations.
diff --git a/include/openPMD/Series.hpp b/include/openPMD/Series.hpp
index 176b8cbe4f..c387c803f7 100644
--- a/include/openPMD/Series.hpp
+++ b/include/openPMD/Series.hpp
@@ -708,7 +708,8 @@ 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.
+     * Synchronous workflow if needed. A shorthand for Synchronous workflows can
+     * be found with Series::writeIterations().
      *
      * @param snapshot_workflow Specify the intended workflow
      *            in Access::CREATE and Access::APPEND. Leave unspecified in
@@ -736,17 +737,9 @@ class Series : public Attributable
     /**
      * @brief Entry point to the writing end of the streaming API.
      *
-     * 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.
+     * Shorthand for `Series::snapshots()` for access types CREATE and APPEND
+     * called with parameter SnapshotWorkflow::Synchronous, i.e. for
+     * streaming-aware data producers.
      *
      * @return WriteIterations
      */
diff --git a/src/Series.cpp b/src/Series.cpp
index 4f34da302f..cee590cc71 100644
--- a/src/Series.cpp
+++ b/src/Series.cpp
@@ -3182,14 +3182,15 @@ void Series::parseBase()
 
 WriteIterations Series::writeIterations()
 {
-    auto &series = get();
-    if (series.m_deferred_initialization.has_value())
+    auto const access = IOHandler()->m_frontendAccess;
+    if (access != Access::CREATE && access != Access::APPEND)
     {
-        runDeferredInitialization();
+        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.");
     }
-    auto begin = make_writing_stateful_iterator(*this, series);
-    return Snapshots(std::shared_ptr<StatefulSnapshotsContainer>(
-        new StatefulSnapshotsContainer(std::move(begin))));
+    return snapshots(SnapshotWorkflow::Synchronous);
 }
 
 void Series::close()