Add Doxygen documentation to new functions and types

Author: AI Agent

include/openPMD/Dataset.hpp

@@ -34,6 +34,12 @@ namespace openPMD
 using Extent = std::vector<std::uint64_t>;
 using Offset = std::vector<std::uint64_t>;
 
+/** Selection of a region of memory for storing chunks.
+ *
+ * Used to specify a non-contiguous memory region when storing
+ * data chunks. This allows writing data that is not contiguous
+ * in memory.
+ */
 struct MemorySelection
 {
     Offset offset;

include/openPMD/Datatype.hpp

@@ -420,6 +420,11 @@ inline size_t toBits(Datatype d)
     return toBytes(d) * CHAR_BIT;
 }
 
+/** Check if a Datatype is a signed type
+ *
+ * @param d Datatype to test
+ * @return true if signed type (integer, floating point, complex), else false
+ */
 constexpr bool isSigned(Datatype d);
 
 /** Compare if a Datatype is a vector type
@@ -602,6 +607,13 @@ inline bool isSameFloatingPoint(Datatype d)
     return isSameFloatingPoint(d, determineDatatype<T_FP>());
 }
 
+/** Compare if two Datatypes are equivalent floating point types
+ *
+ * @param d1 First Datatype to compare
+ * @param d2 Second Datatype to compare
+ * @return true if both types are floating point and have same bitness, else
+ * false
+ */
 inline bool isSameFloatingPoint(Datatype d1, Datatype d2)
 {
     // template
@@ -629,6 +641,13 @@ inline bool isSameComplexFloatingPoint(Datatype d)
     return isSameComplexFloatingPoint(d, determineDatatype<T_CFP>());
 }
 
+/** Compare if two Datatypes are equivalent complex floating point types
+ *
+ * @param d1 First Datatype to compare
+ * @param d2 Second Datatype to compare
+ * @return true if both types are complex floating point and have same bitness,
+ * else false
+ */
 inline bool isSameComplexFloatingPoint(Datatype d1, Datatype d2)
 {
     // template
@@ -656,6 +675,13 @@ inline bool isSameInteger(Datatype d)
     return isSameInteger(d, determineDatatype<T_Int>());
 }
 
+/** Compare if two Datatypes are equivalent integer types
+ *
+ * @param d1 First Datatype to compare
+ * @param d2 Second Datatype to compare
+ * @return true if both types are integers, same signedness and same bitness,
+ * else false
+ */
 inline bool isSameInteger(Datatype d1, Datatype d2)
 {
     // template
@@ -708,13 +734,24 @@ constexpr bool isChar(Datatype d)
 template <typename T_Char>
 constexpr bool isSameChar(Datatype d);
 
+/** Compare if two Datatypes are equivalent char types
+ *
+ * @param d1 First Datatype to compare
+ * @param d2 Second Datatype to compare
+ * @return true if both types are chars with same signedness and size, else
+ * false
+ */
 constexpr bool isSameChar(Datatype d1, Datatype d2);
 
 /** Comparison for two Datatypes
  *
  * Besides returning true for the same types, identical implementations on
  * some platforms, e.g. if long and long long are the same or double and
  * long double will also return true.
+ *
+ * @param d First Datatype to compare
+ * @param e Second Datatype to compare
+ * @return true if the datatypes are equivalent
  */
 constexpr bool isSame(openPMD::Datatype d, openPMD::Datatype e);
 
@@ -726,14 +763,33 @@ constexpr bool isSame(openPMD::Datatype d, openPMD::Datatype e);
  */
 Datatype basicDatatype(Datatype dt);
 
+/** Convert a scalar Datatype to its vector variant
+ *
+ * @param dt Scalar Datatype to convert
+ * @return Vector Datatype (e.g., INT becomes VEC_INT)
+ */
 Datatype toVectorType(Datatype dt);
 
+/** Convert a Datatype to its string representation
+ *
+ * @param dt Datatype to convert
+ * @return String representation of the Datatype
+ */
 std::string datatypeToString(Datatype dt);
 
+/** Convert a string to a Datatype
+ *
+ * @param s String representation of a Datatype
+ * @return The corresponding Datatype
+ */
 Datatype stringToDatatype(const std::string &s);
 
-void warnWrongDtype(std::string const &key, Datatype store, Datatype request);
-
+/** Stream operator for Datatype
+ *
+ * @param os Output stream
+ * @param dt Datatype to output
+ * @return Reference to the stream
+ */
 std::ostream &operator<<(std::ostream &, openPMD::Datatype const &);
 
 template <typename T>

include/openPMD/IO/ADIOS/ADIOS2File.hpp

@@ -108,11 +108,13 @@ struct WriteDataset
     static void call(Params &&...);
 };
 
+/** Buffered put operation with unique pointer */
 struct BufferedUniquePtrPut
 {
     std::string name;
     Offset offset;
     Extent extent;
+    /** Optional memory selection for non-contiguous memory regions */
     std::optional<MemorySelection> memorySelection;
     UniquePtrWithLambda<void> data;
     Datatype dtype = Datatype::UNDEFINED;

include/openPMD/IO/ADIOS/macros.hpp

@@ -45,6 +45,10 @@ namespace openPMD
 {
 namespace detail
 {
+    /** Trait to check if a variable supports SetMemorySelection
+     *
+     * @tparam Variable ADIOS2 variable type
+     */
     template <typename Variable, typename SFINAE = void>
     struct CanTheMemorySelectionBeReset
     {
@@ -60,6 +64,7 @@ namespace detail
     };
 } // namespace detail
 
+/** Whether ADIOS2 Variable supports SetMemorySelection */
 constexpr bool CanTheMemorySelectionBeReset =
     detail::CanTheMemorySelectionBeReset<adios2::Variable<int>>::value;
 } // namespace openPMD

include/openPMD/IO/AbstractIOHandler.hpp

@@ -265,6 +265,12 @@ class AbstractIOHandler
      * backends that decide to implement this operation asynchronously.
      */
     std::future<void> flush(internal::FlushParams const &);
+    /** Counter tracking the number of flush operations. This is later used to
+     * avoid repeated flushing in the DeferredComputation objects returned by
+     * the loadStoreChunk() API. (The counter is copied as a weak reference to
+     * the shared pointer, and the value is compared to the value upon enqueuing
+     * the operation. If the flush counter has proceeded past the old value, our
+     * operation has already been run.) */
     std::shared_ptr<unsigned long long> m_flushCounter =
         std::make_shared<unsigned long long>(0);
 
@@ -319,6 +325,13 @@ class AbstractIOHandler
     bool m_verify_homogeneous_extents = true;
 
 protected:
+    /** Implementation of flush operation for subclasses
+     *
+     * Do not call directly, use flush() wrapper instead.
+     *
+     * @param params Parsed flush parameters
+     * @return Future indicating completion state
+     */
     virtual std::future<void> flush_impl(internal::ParsedFlushParams &) = 0;
 }; // AbstractIOHandler
 

include/openPMD/IO/IOTask.hpp

@@ -495,6 +495,7 @@ struct OPENPMDAPI_EXPORT
 
     Extent extent = {};
     Offset offset = {};
+    /** Optional memory selection for non-contiguous memory regions */
     std::optional<MemorySelection> memorySelection = std::nullopt;
     Datatype dtype = Datatype::UNDEFINED;
     auxiliary::WriteBuffer data;
@@ -559,7 +560,8 @@ struct OPENPMDAPI_EXPORT
     }
 
     // in parameters
-    bool queryOnly = false; // query if the backend supports this
+    /** If true, only query if the backend supports buffer views without performing operation */
+    bool queryOnly = false;
     Offset offset;
     Extent extent;
     Datatype dtype = Datatype::UNDEFINED;

include/openPMD/IO/InvalidatableFile.hpp

@@ -83,6 +83,11 @@ struct hash<openPMD::InvalidatableFile>
     result_type operator()(argument_type const &s) const noexcept;
 };
 
+/** Specialization of std::less for InvalidatableFile
+ *
+ * Enables using InvalidatableFile in ordered containers like std::set
+ * for consistent ordering across parallel processes.
+ */
 template <>
 struct less<openPMD::InvalidatableFile>
 {

include/openPMD/Iteration.hpp

@@ -454,6 +454,12 @@ class Iteration : public Attributable
 
 namespace traits
 {
+    /** Generation policy for Iteration objects.
+     *
+     * This policy populates the cached iteration index when an Iteration
+     * is created or inserted into a Series, enabling constant-time lookup
+     * of the owning map entry.
+     */
     template <>
     struct GenerationPolicy<Iteration>
     {