WIP: Documentation

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.

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
      */

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()