Add Doxygen docu for AdvanceStatus and for SeriesStatus

Author: franzpoeschel

include/openPMD/IO/AbstractIOHandler.hpp

@@ -122,10 +122,26 @@ namespace internal
 
     struct ParsedFlushParams;
 
+    /**
+     * Some parts of the openPMD object model are read-only when accessing
+     * a Series in Access::READ_ONLY mode, notably Containers and Attributes.
+     * They are filled at parse time and not modified afterwards.
+     * Such state-changing operations are hence allowed under either of two
+     * conditions:
+     * 1) The Series is opened in an open mode that allows writing in any way.
+     *    (Currently any but Access::READ_ONLY).
+     * 2) The Series is in Parsing state. This way, modifying the open mode
+     *    during parsing can be avoided.
+     */
     enum class SeriesStatus : unsigned char
     {
-        Default,
-        Parsing
+        Default, ///< Mutability of objects in the openPMD object model is
+                 ///< determined by the open mode (Access enum), normal state in
+                 ///< which the user interacts with the Series.
+        Parsing ///< All objects in the openPMD object model are temporarily
+                ///< mutable to allow inserting newly-parsed data.
+                ///< Special state only active while internal routines are
+                ///< running.
     };
 } // namespace internal
 

include/openPMD/Streaming.hpp

@@ -19,9 +19,9 @@ namespace openPMD
  */
 enum class AdvanceStatus : unsigned char
 {
-    OK, /* stream goes on */
-    OVER, /* stream is over */
-    RANDOMACCESS /* there is no stream, it will never be over */
+    OK, ///< stream goes on
+    OVER, ///< stream is over
+    RANDOMACCESS ///< there is no stream, it will never be over
 };
 
 /**