From 970094a52a2de3ebd728fd82b742431c74596f2b Mon Sep 17 00:00:00 2001 From: Daniel Garcia-Sanchez Date: Fri, 5 Oct 2018 11:56:43 +0200 Subject: [PATCH] Improve the documentation Improve the documentation of hyperslab Document hdf5_reference std::shared_ptr<> Document DataSet constructors --- include/deal.II/base/hdf5.h | 43 ++++++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 10 deletions(-) diff --git a/include/deal.II/base/hdf5.h b/include/deal.II/base/hdf5.h index 84945e3e0a..39f06d66aa 100644 --- a/include/deal.II/base/hdf5.h +++ b/include/deal.II/base/hdf5.h @@ -134,9 +134,9 @@ DEAL_II_NAMESPACE_OPEN * href="https://support.hdfgroup.org/HDF5/doc1.8/RM/RM_H5S.html#Dataspace-SelectHyperslab">H5Sselect_hyperslab * definition. * - * The example below shows how to write a simple hyperslab. The offset defines - * the origin of the hyperslab in the original dataset. The dimensions parameter - * defines the dimensions of the data to be written. + * The example below shows how to write a simple rectangular hyperslab. The + * offset defines the origin of the hyperslab in the original dataset. The + * dimensions of the hyperslab are `hyperslab_dimensions = {2, 5}`. * @code * std::vector dataset_dimensions = {50, 30}; * auto dataset = group.create_dataset("name", dataset_dimensions); @@ -145,7 +145,7 @@ DEAL_II_NAMESPACE_OPEN * // data can be std::vector, FullMatrix or Vector * FullMatrix data = {...}; * std::vector hyperslab_dimensions = {2, 5}; - * std::vector hyperslab_offset = {0, 0}; + * std::vector hyperslab_offset = {1, 2}; * dataset.write_hyperslab(hyperslab_data, * hyperslab_offset, * hyperslab_dimensions); @@ -155,6 +155,17 @@ DEAL_II_NAMESPACE_OPEN * dataset.write_none(); * } * @endcode + */ +// It is necessary to turn clang-format off in order to maintain the Doxygen +// link +// clang-format off +/** + * The function + * DataSet::write_hyperslab(const Container &,const std::vector &, const std::vector &, const std::vector &, const std::vector &, const std::vector &) + * can be used to write complex hyperslabs. + */ +// clang-format on +/** * * ## Write unordered data in parallel * The example below shows how to write a selection of data. @@ -196,13 +207,13 @@ DEAL_II_NAMESPACE_OPEN * * ## Query the I/O mode that HDF5 used on the last parallel I/O call * The default access mode in the HDF5 C++ interface of deal.ii is collective - * which is typically faster since it allows MPI to do more optimization. In + * which is typically faster since it allows MPI to do more optimizations. In * some cases, such as when there is type conversion, the HDF5 library can * decide to do independent I/O instead of collective I/O, even if the user asks * for collective I/O. See the following * [article](https://www.hdfgroup.org/2015/08/parallel-io-with-hdf5/) * - * In cases where maximum performance has to be achieved, it is important to + * In cases where maximum performance is a requirement, it is important to * make sure that all MPI read/write operations are collective. The HDF5 library * provides API routines that can be used after the read/write I/O operations to * query the I/O mode. If DataSet::query_io_mode() is set to True, then after @@ -305,7 +316,11 @@ namespace HDF5 protected: /** - * HDF5 identifier for the objects File, Group and DataSet + * HDF5 identifier for the objects File, Group and DataSet. The + * `std::share_ptr<>` pointer allows the object to be copied. For example + * several parts of the program can share and access the same group; when + * all the functions that access the group are closed, the HDF5 resources of + * the group will be automatically released. */ std::shared_ptr hdf5_reference; @@ -339,10 +354,16 @@ namespace HDF5 friend class Group; protected: - // Open dataset + /** + * Open dataset. This is an internal constructor. The function + * Group::dataset() should be used to open a dataset. + */ DataSet(const std::string &name, const hid_t &parent_group_id, bool mpi); - // Create dataset + /** + * Create dataset. This is an internal constructor. The function + * Group::create_dataset() should be used to create a dataset. + */ DataSet(const std::string & name, const hid_t & parent_group_id, const std::vector &dimensions, @@ -486,10 +507,12 @@ namespace HDF5 * - Offset: The starting location for the hyperslab. * - Count: The number of elements to select along each dimension. */ + // It is necessary to turn clang-format off in order to maintain the Doxygen + // link // clang-format off /** * - * Stride and block are set to NULL. For more complex hyperslabs see + * Stride and block are set to NULL. For complex hyperslabs see * write_hyperslab(const Container &data, const std::vector &data_dimensions, const std::vector &offset, const std::vector &stride, const std::vector &count, const std::vector &block). */ // clang-format on -- 2.39.5