Fix the documentation

Author: franzpoeschel

docs/source/details/mpi.rst

@@ -30,6 +30,7 @@ Functionality Behavior Description
 ``::resetDataset`` [1]_ [2]_ *backend-specific* declare, write
 ``::makeConstant`` [3]_ *backend-specific* declare, write
 ``::storeChunk`` [1]_ independent write
+``::storeChunk`` [5]_ collective Span-based overloads
 ``::loadChunk`` independent read
 ``::availableChunks`` [4]_ collective read, immediate result
 ============================ ================== ================================
@@ -49,6 +50,8 @@ Functionality Behavior Description
 .. [4] We usually open iterations delayed on first access. This first access is usually the ``flush()`` call after a ``storeChunk``/``loadChunk`` operation. If the first access is non-collective, an explicit, collective ``Iteration::open()`` can be used to have the files already open.
  Alternatively, iterations might be accessed for the first time by immediate operations such as ``::availableChunks()``.
 
+.. [5] The Span-based ``storeChunk`` API calls return a backend-allocated pointer, requiring flush operations. These API calls hence inherit the collective properties of flushing. Use store calls with zero-size extent if a rank does not contribute anything.
+
 .. warning::
 
  The openPMD-api will by default flush only those Iterations which are dirty, i.e. have been written to.

include/openPMD/RecordComponent.hpp

@@ -417,6 +417,11 @@ class RecordComponent : public BaseRecordComponent
  * @brief Overload of storeChunk() that lets the openPMD API allocate
  * a buffer.
  *
+ * Collective call: Unlike most other storeChunk() calls, this call returns
+ * pointers allocated by the IO backends and hence inherits the collective
+ * properties of flushing. Apply zero-extent storeChunk() calls from ranks
+ * that do not contribute anything.
+ *
  * This may save memory if the openPMD backend in use is able to provide
  * users a view into its own buffers, avoiding the need to allocate
  * a new buffer.
@@ -453,6 +458,11 @@ class RecordComponent : public BaseRecordComponent
  /**
  * Overload of span-based storeChunk() that uses operator new() to create
  * a buffer.
+ *
+ * Collective call: Unlike most other storeChunk() calls, this call returns
+ * pointers allocated by the IO backends and hence inherits the collective
+ * properties of flushing. Apply zero-extent storeChunk() calls from ranks
+ * that do not contribute anything.
  */
  template <typename T>
  DynamicMemoryView<T> storeChunk(Offset, Extent);