Fix docs for H5Pset_dxpl_mpio_collective_opt() (HDFGroup#3594)

hyoklee · Sep 25, 2023 · 08b574d · 08b574d
1 parent 1e852b9
commit 08b574d
Show file tree

Hide file tree

Showing 2 changed files with 21 additions and 15 deletions.
diff --git a/src/H5FDmpio.c b/src/H5FDmpio.c
@@ -559,13 +559,13 @@ H5Pget_dxpl_mpio(hid_t dxpl_id, H5FD_mpio_xfer_t *xfer_mode /*out*/)
 /*-------------------------------------------------------------------------
  * Function:    H5Pset_dxpl_mpio_collective_opt
  *
- * Purpose:     To set a flag to choose linked chunk I/O or multi-chunk I/O
- *              without involving decision-making inside HDF5
- *
- * Note:        The library will do linked chunk I/O or multi-chunk I/O without
- *              involving communications for decision-making process.
- *              The library won't behave as it asks for only when we find
- *              that the low-level MPI-IO package doesn't support this.
+ * Purpose:     Set the data transfer property list DXPL_ID to use transfer
+ *              mode OPT_MODE during I/O. This allows the application to
+ *              specify collective I/O at the HDF5 interface level (with
+ *              the H5Pset_dxpl_mpio routine), while controlling whether
+ *              the actual I/O is performed collectively (e.g., via
+ *              MPI_File_write_at_all) or independently (e.g., via
+ *              MPI_File_write_at).
  *
  * Return:      Success:    Non-negative
  *              Failure:    Negative
@@ -2032,7 +2032,7 @@ H5FD__mpio_vector_build_types(uint32_t count, H5FD_mem_t types[], haddr_t addrs[
 /*-------------------------------------------------------------------------
  * Function:    H5FD__mpio_read_vector()
  *
- * Purpose:     The behaviour of this function dependes on the value of
+ * Purpose:     The behavior of this function depends on the value of
  *              the io_xfer_mode obtained from the context.
  *
  *              If it is H5FD_MPIO_COLLECTIVE, this is a collective

diff --git a/src/H5FDmpio.h b/src/H5FDmpio.h
@@ -164,18 +164,24 @@ H5_DLL herr_t H5Pget_dxpl_mpio(hid_t dxpl_id, H5FD_mpio_xfer_t *xfer_mode /*out*
 /**
  * \ingroup DXPL
  *
- * \brief Sets data transfer mode
+ * \brief Sets low-level data transfer mode
  *
  * \dxpl_id
  * \param[in] opt_mode Transfer mode
  * \returns \herr_t
  *
- * \details H5Pset_dxpl_mpio() sets the data transfer property list \p dxpl_id
- *          to use transfer mode xfer_mode. The property list can then be used
- *          to control the I/O transfer mode during data I/O operations.
- *
- *          Valid transfer modes are #H5FD_MPIO_INDEPENDENT (default) and
- *          #H5FD_MPIO_COLLECTIVE.
+ * \details H5Pset_dxpl_mpio_collective_opt() sets the data transfer property
+ *          list \p dxpl_id to use transfer mode \p opt_mode when performing
+ *          I/O. This allows the application to specify collective I/O at the
+ *          HDF5 interface level (with the H5Pset_dxpl_mpio() API routine),
+ *          while controlling whether the actual I/O is performed collectively
+ *          (e.g., via MPI_File_write_at_all) or independently (e.g., via
+ *          MPI_File_write_at). If the collectivity setting at the HDF5
+ *          interface level (set via H5Pset_dxpl_mpio()) is not set to
+ *          H5FD_MPIO_COLLECTIVE, this setting will be ignored.
+ *
+ *          Valid transfer modes are #H5FD_MPIO_COLLECTIVE_IO (default) and
+ *          #H5FD_MPIO_INDIVIDUAL_IO.
  *
  * \since 1.4.0
  *