Switch to doxygen to generate documentation

CMakeLists.txt

@@ -58,9 +58,6 @@ option(PythonSupport "Build with Python support" ON)
 
 # Documentation
 option(Build_Documentation "Build documentation" OFF)
-if(NOT IS_SUBPROJECT AND (Build_Documentation AND NOT PythonSupport))
-  message(FATAL_ERROR "Build_Documentation=ON requires PythonSupport to be enabled")
-endif()
 
 # Testing
 option(Build_Tests "Build tests" ON)

c++/h5/array_interface.cpp

@@ -14,6 +14,11 @@
 //
 // Authors: Olivier Parcollet, Nils Wentzell
 
+/**
+ * @file
+ * @brief Implementation details for array_interface.hpp.
+ */
+
 #include "./array_interface.hpp"
 #include "./macros.hpp"
 #include "./stl/string.hpp"

c++/h5/array_interface.hpp

@@ -30,6 +30,11 @@
 
 namespace h5::array_interface {
 
+  /**
+   * @addtogroup rw_arrayinterface
+   * @{
+   */
+
   /// Simple struct to store basic information about an n-dimensional array/dataspace.
   struct h5_lengths_type {
     /// Shape of the array/dataspace.
@@ -251,6 +256,8 @@ namespace h5::array_interface {
    */
   void read_attribute(object obj, std::string const &name, h5_array_view v);
 
+  /** @} */
+
 } // namespace h5::array_interface
 
 #endif // LIBH5_ARRAY_INTERFACE_HPP

c++/h5/complex.hpp

@@ -28,8 +28,12 @@
 namespace h5 {
 
   /**
+   * @ingroup h5_types
    * @brief A complex compound type consisting of two doubles to represent a complex number.
+   *
    * @details This type can be used to read/write complex numbers from/to HDF5 files.
+   *
+   * @note **h5** also supports the direct use of std::complex which is the recommended way to read/write complex data.
    */
   struct dcplx_t {
     /// Real part.
@@ -48,6 +52,7 @@ namespace h5 {
   struct _is_complex<std::complex<T>> : std::true_type {};
 
   /**
+   * @ingroup h5_types
    * @brief Boolean type trait set to true for std::complex types.
    * @tparam T Type to check.
    */

c++/h5/file.cpp

@@ -14,6 +14,11 @@
 //
 // Authors: Olivier Parcollet, Nils Wentzell
 
+/**
+ * @file
+ * @brief Implementation details for file.hpp.
+ */
+
 #include "./file.hpp"
 
 #include <hdf5.h>

c++/h5/file.hpp

@@ -32,6 +32,7 @@
 namespace h5 {
 
   /**
+   * @ingroup data_model
    * @brief A handle to an HDF5 file.
    *
    * @details This class inherits from the general h5::object class. It simply wraps the HDF5 functions

c++/h5/format.cpp

@@ -14,6 +14,11 @@
 //
 // Authors: Olivier Parcollet, Nils Wentzell
 
+/**
+ * @file
+ * @brief Implementation details for format.hpp.
+ */
+
 #include "./format.hpp"
 #include "./group.hpp"
 #include "./object.hpp"

c++/h5/format.hpp

@@ -35,6 +35,11 @@
 
 namespace h5 {
 
+  /**
+   * @addtogroup format
+   * @{
+   */
+
   /**
    * @brief Default type trait to get the `hdf5_format` tag of type `T` by calling its static member function
    * `T::hdf5_format()`.
@@ -160,6 +165,8 @@ namespace h5 {
     assert_hdf5_format_as_string(g, get_hdf5_format<T>().c_str(), ignore_if_absent);
   }
 
+  /** @} */
+
 } // namespace h5
 
 #endif // LIBH5_FORMAT_HPP

c++/h5/generic.hpp

@@ -31,6 +31,11 @@
 
 namespace h5 {
 
+  /**
+   * @addtogroup rw_generic
+   * @{
+   */
+
   /**
    * @brief Generic implementation for reading from an HDF5 dataset/subgroup.
    *
@@ -203,6 +208,8 @@ namespace h5 {
     return false;
   }
 
+  /** @} */
+
 } // namespace h5
 
 #endif // LIBH5_GENERIC_HPP

c++/h5/group.cpp

@@ -14,6 +14,11 @@
 //
 // Authors: Henri Menke, Olivier Parcollet, Nils Wentzell
 
+/**
+ * @file
+ * @brief Implementation details for group.hpp.
+ */
+
 #include "./group.hpp"
 
 #include <hdf5.h>

c++/h5/group.hpp

@@ -32,6 +32,7 @@
 namespace h5 {
 
   /**
+   * @ingroup data_model
    * @brief A handle to an HDF5 group.
    *
    * @details This class inherits from the general h5::object class. Each group stores the parent h5::file

c++/h5/h5.hpp

@@ -32,6 +32,7 @@
 #include "./group.hpp"
 #include "./object.hpp"
 #include "./scalar.hpp"
+#include "./utils.hpp"
 #include "./stl/string.hpp"
 #include "./stl/array.hpp"
 #include "./stl/vector.hpp"
@@ -54,6 +55,7 @@
 namespace h5 {
 
   /**
+   * @ingroup utilities
    * @brief Concept to check if a type can be read/written from/to HDF5.
    * @tparam T Type to check.
    */

c++/h5/object.cpp

@@ -14,9 +14,15 @@
 //
 // Authors: Olivier Parcollet, Nils Wentzell
 
+/**
+ * @file
+ * @brief Implementation details for object.hpp.
+ */
+
 #include "./complex.hpp"
 #include "./macros.hpp"
 #include "./object.hpp"
+#include "./utils.hpp"
 
 #include <H5Ipublic.h>
 #include <H5Fpublic.h>

c++/h5/object.hpp

@@ -22,35 +22,16 @@
 #ifndef LIBH5_OBJECT_HPP
 #define LIBH5_OBJECT_HPP
 
-#include <cstdint>
+#include "./utils.hpp"
+
 #include <string>
-#include <vector>
 
 namespace h5 {
 
   /**
-   * @brief ID type used in HDF5.
-   *
-   * @details This is just a copy from the HDF5 library (see the official
-   * <a href="https://docs.hdfgroup.org/hdf5/develop/_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">documentation</a>).
-   * It is used to completely isolate our header from the HDF5 headers. In the .cpp file a `static_assert` is used to verify
-   * its validity.
-   */
-  using hid_t = int64_t;
-
-  /**
-   * @brief Size type used in HDF5.
-   * @details This is just a copy from the HDF5 library. It is used to completely isolate our header from the HDF5 headers.
-   * In the .cpp file a `static_assert` is used to verify its validity.
+   * @addtogroup data_model
+   * @{
    */
-#ifdef H5_VER_GE_113
-  using hsize_t = uint64_t;
-#else
-  using hsize_t = unsigned long long;
-#endif
-
-  /// Vector of h5::hsize_t used throughout the h5 library.
-  using v_t = std::vector<hsize_t>;
 
   /**
    * @brief A generic handle for HDF5 objects.
@@ -61,9 +42,9 @@ namespace h5 {
    * destructor, the derived classes should not be deleted through a pointer to this class. It is recommended
    * to use the derived classes whenever possible.
    *
-   * HDF5's reference counting system is similar to python. This class handles the proper reference counting
+   * HDF5's reference counting system is similar to Python's. This class handles the proper reference counting
    * using a RAII pattern (hence exception safe). Depending on how the object is constructed, it either
-   * increases the reference count associated HDF5 object or steals it.
+   * increases the reference count associated with the HDF5 object or steals it.
    */
   class object {
     protected:
@@ -150,6 +131,13 @@ namespace h5 {
   /// Type alias for an HDF5 attribute.
   using attribute = object;
 
+  /** @} */
+
+  /**
+   * @addtogroup h5_types
+   * @{
+   */
+
   namespace detail {
 
     // Map a C++ type to an HDF5 type (specializations are in object.cpp).
@@ -188,7 +176,7 @@ namespace h5 {
   [[nodiscard]] datatype get_hdf5_type(dataset ds);
 
   /**
-   * @brief Check two HDF5 datatypes for equality.
+   * @brief Check if two HDF5 datatypes are equal.
    *
    * @details For string types, this function only checks if they are both of the class `H5T_STRING`.
    * It does not take into account the size, character set, etc.
@@ -201,6 +189,8 @@ namespace h5 {
    */
   [[nodiscard]] bool hdf5_type_equal(datatype dt1, datatype dt2);
 
+  /** @} */
+
 } // namespace h5
 
 #endif // LIBH5_OBJECT_HPP

c++/h5/scalar.hpp

@@ -37,6 +37,7 @@ namespace h5 {
   namespace array_interface {
 
     /**
+     * @ingroup rw_arrayinterface
      * @brief Create an array view for a scalar.
      *
      * @tparam T Scalar type.
@@ -50,6 +51,11 @@ namespace h5 {
 
   } // namespace array_interface
 
+  /**
+   * @addtogroup rw_scalar
+   * @{
+   */
+
   /**
    * @brief Write a scalar to an HDF5 dataset.
    *
@@ -135,6 +141,8 @@ namespace h5 {
     array_interface::read_attribute(obj, name, array_interface::h5_array_view_from_scalar(x));
   }
 
+  /** @} */
+
 } // namespace h5
 
 #endif // LIBH5_SCALAR_HPP

c++/h5/serialization.hpp

@@ -30,6 +30,11 @@
 
 namespace h5 {
 
+  /**
+   * @addtogroup serialize
+   * @{
+   */
+
   /**
    * @brief Serialize an object to a byte buffer.
    *
@@ -53,14 +58,16 @@ namespace h5 {
    *
    * @tparam T Type of the object.
    * @param buf Byte buffer containing the serialized object.
-   * @return Deserialized object.
+   * @return Object restored from the given byte buffer.
    */
   template <typename T>
   [[nodiscard]] T deserialize(std::vector<std::byte> const &buf) {
     file f{buf};
     return h5_read<T>(f, "object");
   }
 
+  /** @} */
+
 } // namespace h5
 
 #endif // LIBH5_SERIALIZATION_HPP

c++/h5/stl/array.hpp

@@ -34,6 +34,11 @@
 
 namespace h5 {
 
+  /**
+   * @addtogroup rw_array
+   * @{
+   */
+
   /**
    * @brief Write a std::array to an HDF5 dataset/subgroup.
    *
@@ -128,6 +133,8 @@ namespace h5 {
     }
   }
 
+  /** @} */
+
 } // namespace h5
 
 #endif // LIBH5_STL_ARRAY_HPP

c++/h5/stl/map.hpp

@@ -33,6 +33,11 @@
 
 namespace h5 {
 
+  /**
+   * @addtogroup rw_map
+   * @{
+   */
+
   /// Specialization of h5::hdf5_format_impl for std::map.
   template <typename keyT, typename valueT>
   struct hdf5_format_impl<std::map<keyT, valueT>> {
@@ -103,6 +108,8 @@ namespace h5 {
     }
   }
 
+  /** @} */
+
 } // namespace h5
 
 #endif // LIBH5_STL_MAP_HPP

c++/h5/stl/optional.hpp

@@ -31,6 +31,11 @@
 
 namespace h5 {
 
+  /**
+   * @addtogroup rw_optional
+   * @{
+   */
+
   /// Specialization of h5::hdf5_format_impl for std::optional.
   template <typename T>
   struct hdf5_format_impl<std::optional<T>> {
@@ -68,6 +73,8 @@ namespace h5 {
     if (g.has_key(name)) opt.emplace(h5_read<T>(g, name));
   }
 
+  /** @} */
+
 } // namespace h5
 
 #endif // LIBH5_STL_OPTIONAL_HPP