Updating and adding more documentation in readthedocs

bindings/CXX11/cxx11/Engine.h

@@ -246,8 +246,8 @@ class Engine
      * @param datum user data to be populated, r-value or single data value
      * @param launch mode policy, optional for API consistency, internally
      * is always sync
-     * @exception std::invalid_argument if variable is invalid or nullptr
-     * &datum
+     * @exception std::invalid_argument for invalid variableName (variable
+     * doesn't exist in IO) or nullptr data
      */
     template <class T>
     void Get(const std::string &variableName, T &datum,
@@ -277,7 +277,7 @@ class Engine
      * Get data associated with a Variable from the Engine.
      * Overloaded version that accepts a std::vector without pre-allocation.
      * @param variableName find variable by name inside IO that created this
-     * Engine with Open
+     * Engine with Open or BeginStep (streaming mode)
      * @param dataV user data vector to be associated with a variable, it
      * doesn't need to be pre-allocated. Engine will resize.
      * @param launch mode policy
@@ -289,7 +289,8 @@ class Engine
      * immediately.
      * Special case, only use if necessary.
      * </pre>
-     * @exception std::invalid_argument for invalid variable
+     * @exception std::invalid_argument for invalid variableName (variable
+     * doesn't exist in IO)
      */
     template <class T>
     void Get(const std::string &variableName, std::vector<T> &dataV,
@@ -322,7 +323,8 @@ class Engine
      * variable's BlockInfo. Overloaded version
      * to get variable by name.
      * @note Preliminary, experimental API, may change soon.
-     * @param variable contains variable metadata information
+     * @param variableName find variable by name inside IO that created this
+     * Engine with Open or BeginStep (streaming mode)
      * @param info block info struct associated with block selection,
      *   call will link with implementation's block info.
      * @param launch mode policy
@@ -333,7 +335,8 @@ class Engine
      * immediately.
      * Special case, only use if necessary.
      * </pre>
-     * @exception std::invalid_argument for invalid variable or nullptr data
+     * @exception std::invalid_argument for invalid variableName (variable
+     * doesn't exist in IO)
      */
     template <class T>
     void Get(const std::string &variableName, typename Variable<T>::Info &info,

bindings/CXX11/cxx11/Variable.h

@@ -234,17 +234,26 @@ class Variable
      */
     T Max(const size_t step = adios2::DefaultSizeT) const;
 
-    /** Contains sub-block information for a particular Variable<T> */
+    /** Contains block information for a particular Variable<T> */
     struct Info
     {
-        adios2::Dims Start;      ///< block start
-        adios2::Dims Count;      ///< block count
-        IOType Min = IOType();   ///< block Min, if IsValue is false
-        IOType Max = IOType();   ///< block Max, if IsValue is false
-        IOType Value = IOType(); ///< block Value, if IsValue is true
-        bool IsValue = false;    ///< true: value, false: array
-        size_t BlockID = 0;      ///< block ID for block selections
+        /** block start */
+        adios2::Dims Start;
+        /** block count */
+        adios2::Dims Count;
+        /** block Min, if IsValue is false */
+        IOType Min = IOType();
+        /** block Max, if IsValue is false */
+        IOType Max = IOType();
+        /** block Value, if IsValue is true */
+        IOType Value = IOType();
+        /** true: value, false: array */
+        bool IsValue = false;
+        /** blockID for Block Selection */
+        size_t BlockID = 0;
+        /** block corresponding step */
         size_t Step = 0;
+        /** reference to internal block data (used by inline Engine) */
         const T *Data() const;
 
         // allow Engine to set m_Info
@@ -268,27 +277,79 @@ class Variable
     class Span
     {
     public:
+        /** Span can only be created by an Engine */
         Span() = delete;
+        /** Span can't be copied */
         Span(const Span &) = delete;
+        /** Span can be moved */
         Span(Span &&) = default;
+        /**
+         * Memory is not owned, using RAII for members
+         */
         ~Span() = default;
 
+        /** Span can't be copied */
         Span &operator=(const Span &) = delete;
+        /** Span can only be moved */
         Span &operator=(Span &&) = default;
 
+        /**
+         * size of the span based on Variable block Count
+         * @return number of elements
+         */
         size_t size() const noexcept;
+
+        /**
+         * Pointer to span data, can be modified if new spans are added
+         * Follows rules of std::vector iterator invalidation.
+         * Call again to get an updated pointer.
+         * @return pointer to data
+         */
         T *data() const noexcept;
 
+        /**
+         * Safe access operator that checks bounds and throws an exception
+         * @param position input offset from 0 = data()
+         * @return span element at input position
+         * @throws std::invalid_argument if out of bounds
+         */
         T &at(const size_t position);
+
+        /**
+         * Safe const access operator that checks bounds and throws an exception
+         * @param position input offset from 0 = data()
+         * @return span const (read-only) element at input position
+         * @throws std::invalid_argument if out of bounds
+         */
         const T &at(const size_t position) const;
 
+        /**
+         * Access operator (unsafe without check overhead)
+         * @param position input offset from 0 = data()
+         * @return span element at input position
+         */
         T &operator[](const size_t position);
+
+        /**
+         * Access const operator (unsafe without check overhead)
+         * @param position input offset from 0 = data()
+         * @return span const (read-only) element at input position
+         */
         const T &operator[](const size_t position) const;
 
         // engine allowed to set m_Span
         friend class Engine;
 
+        /**
+         * Custom iterator class from:
+         * https://gist.github.com/jeetsukumaran/307264#file-custom_iterator-cpp-L26
+         */
         ADIOS2_CLASS_iterator;
+
+        /**
+         * Custom iterator class functions from:
+         * https://gist.github.com/jeetsukumaran/307264#file-custom_iterator-cpp-L26
+         */
         ADIOS2_iterators_functions(data(), size());
 
     private:

bindings/CXX11/cxx11/fstream/ADIOS2fstream.h

@@ -234,7 +234,7 @@ class fstream
      */
     template <class T>
     void write_attribute(const std::string &name, const T *data,
-                         const size_t elements,
+                         const size_t size,
                          const std::string &variableName = "",
                          const std::string separator = "/",
                          const bool endStep = false);

bindings/CXX11/cxx11/fstream/ADIOS2fstream.tcc

@@ -30,13 +30,13 @@ void fstream::write_attribute(const std::string &name, const T &value,
 
 template <class T>
 void fstream::write_attribute(const std::string &name, const T *data,
-                              const size_t elements,
+                              const size_t size,
                               const std::string &variableName,
                               const std::string separator, const bool endStep)
 {
     using IOType = typename TypeInfo<T>::IOType;
-    m_Stream->WriteAttribute(name, reinterpret_cast<const IOType *>(data),
-                             elements, variableName, separator, endStep);
+    m_Stream->WriteAttribute(name, reinterpret_cast<const IOType *>(data), size,
+                             variableName, separator, endStep);
 }
 
 template <class T>

bindings/Python/py11glue.cpp

@@ -743,25 +743,25 @@ PYBIND11_MODULE(adios2, m)
              pybind11::arg("separator") = "/",
              pybind11::arg("end_step") = false,
              R"md(
-				 writes a self-describing single value array (numpy) variable
+			 writes a self-describing single value array (numpy) variable
 
-				 Parameters
-					 name
-						 attribute name
+			 Parameters
+				 name
+					 attribute name
 
-					 stringvalue:  
-						 attribute single string
+				 stringvalue:  
+					 attribute single string
 
-					 variablename:
-						 if attribute is associated with a variable
+				 variablename:
+					 if attribute is associated with a variable
 
-					 separator:
-						 concatenation string between variablename and attribute
-						 e.g. variablename + separator + name
-							  var/units. Not used if variablename is empty 
-					 endstep 
-						 end current step, begin next step and flush 
-						 (default = false).
+				 separator:
+					 concatenation string between variablename and attribute
+					 e.g. variablename + separator + name
+						  var/units. Not used if variablename is empty 
+				 endstep 
+					 end current step, begin next step and flush 
+					 (default = false).
 			)md")
 
         .def("write_attribute",
@@ -774,25 +774,25 @@ PYBIND11_MODULE(adios2, m)
              pybind11::arg("separator") = "/",
              pybind11::arg("end_step") = false,
              R"md(
-				 writes a self-describing single value array (numpy) variable
+			 writes a self-describing single value array (numpy) variable
 
-				 Parameters
-					 name
-						 attribute name
+			 Parameters
+				 name
+					 attribute name
 
-					 stringarray:  
-						 attribute string array
+				 stringarray:  
+					 attribute string array
 
-					 variablename:
-						 if attribute is associated with a variable
+				 variablename:
+					 if attribute is associated with a variable
 
-					 separator:
-						 concatenation string between variablename and attribute
-						 e.g. variablename + separator + name
-							  var/units. Not used if variablename is empty 
-					 endstep 
-						 end current step, begin next step and flush 
-						 (default = false).
+				 separator:
+					 concatenation string between variablename and attribute
+					 e.g. variablename + separator + name
+						  var/units. Not used if variablename is empty 
+				 endstep 
+					 end current step, begin next step and flush 
+					 (default = false).
 			)md")
 
         .def("read_string",
@@ -923,22 +923,22 @@ PYBIND11_MODULE(adios2, m)
              pybind11::arg("name"), pybind11::arg("variable_name") = "",
              pybind11::arg("separator") = "/",
              R"md(
-				 Reads a numpy based attribute
+			 Reads a numpy based attribute
 
-				 Parameters
-					 name
-						 attribute name
-					 
-					 variablename:
-						 if attribute is associated with a variable
-
-					 separator:
-						 concatenation string between variablename and attribute
-						 e.g. variablename + separator + name
-							  var/units. Not used if variablename is empty 
-				Returns
-		 			 array: numpy
-						 resulting array attribute data
+			 Parameters
+				 name
+					 attribute name
+
+				 variablename:
+					 if attribute is associated with a variable
+
+				 separator:
+					 concatenation string between variablename and attribute
+					 e.g. variablename + separator + name
+						  var/units. Not used if variablename is empty 
+			Returns
+				 array: numpy
+					 resulting array attribute data
 	    )md")
 
         .def("read_attribute_string",
@@ -949,22 +949,22 @@ PYBIND11_MODULE(adios2, m)
              pybind11::arg("name"), pybind11::arg("variable_name") = "",
              pybind11::arg("separator") = "/",
              R"md(
-				 Read a string attribute
+			 Read a string attribute
 
-				 Parameters
-					 name
-						 attribute name
-					 
-					 variablename:
-						 if attribute is associated with a variable
-
-					 separator:
-						 concatenation string between variablename and attribute
-						 e.g. variablename + separator + name
-							  var/units. Not used if variablename is empty 
-				Returns
-					 list: 
-						 resulting string list attribute data 
+			 Parameters
+				 name
+					 attribute name
+
+				 variablename:
+					 if attribute is associated with a variable
+
+				 separator:
+					 concatenation string between variablename and attribute
+					 e.g. variablename + separator + name
+						  var/units. Not used if variablename is empty 
+			Returns
+				 list: 
+					 resulting string list attribute data 
 		)md")
 
         .def("end_step", &adios2::py11::File::EndStep, R"md(