Merge doxygen2 into develop (#553)

* Fixed warnings and started H5Epublic.h.

* Include H5FD* headers to correctly resolve references.

* Doxygen2 (#330)

* H5Eauto_is_v2.

* Added a few more calls.

* Added a few more H5E calls.

* First cut of H5E v2.

* Added the deprecated v1 calls.

* Updated spacing.

* Once more.

* Taking some inspiration from Eigen3.

* Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pen… (#352)

* Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pencode1, H5Pget_filter_by_id1,H5Pget_version, H5Pset_file_space,H5Pget_file_space. Someone already adds H5Pget_filter1. Also fixs an extra parameter 'close' call back function for HPregister2.

* doxygen work. fixs format by using clang-format.

* doxgen work for H5Pregister1 etc. Addressed Barbara and Gerd's comments.
For Quincey's comments, since we are not supposed to change the source code.
I leave this to future improvements.

* added documentation for H5P APIs (#350)

* add documenation for H5Pget_buffer,H5Pget_data_transform,H5Pget_edc_check,H5Pget_hyper_vector_size,H5Pget_preserve,H5Pget_type_conv_cb,H5Pget_vlen_mem_manager,H5Pset_btree_ratios

* format corrections

* fixed grammer

* fixed herr_t

* Better name.

* A fresh look.

* add doxygen to H5Ppublic.h

* use attention instead of warning

* Add doxygen comments in H5Ppublic.h (#375)

* Add doxygen comments in H5Ppublic.h

* H5Pset_meta_block_size
* H5Pset_metadata_read_attempts
* H5Pset_multi_type
* H5Pset_object_flush_cb
* H5Pset_sieve_buf_size
* H5Pset_small_data_block_size
* H5Pset_all_coll_metadata_ops
* H5Pget_all_coll_metadata_ops

* Add DOXYGEN_EXAMPLES_DIR to src/CMakeLists.txt

* Fix clang-format errors

* Fix filenames in doxygen/examples

* add doxygen to H5Ppublic.h (#378)

* add doxygen to H5Ppublic.h

* use attention instead of warning

Co-authored-by: Kimmy Mu <kmu@hdfgroup.org>

* Revert "add doxygen to H5Ppublic.h (#378)"

This reverts commit 2ee1821b138a5c00b15ea57ce9e950367480f5f2.

* Updated Doxygen variables.

* I forgot to copy two images.

* Enable desktop search by default.

* Add my assigned Doxygen documentation.

* Remove whitespace at EOL.  Appease clang-format.

* Addressed Chris' comments.

* Added an alias for asynchronous functions.

* One space is enough for all of us.

* Slightly restructured RM page.

* address some issues

* reformatting

* Style external links.

* reformatting

* reformatting

* Added "Metadata Caching in HDF5" as a technical note example.

* Revise this soon!

* Added specification examples.

* Fixed references.

* Added H5AC cache image stuff and file format study.

* Added older FMT versions. Where did 1.0 go?

* Updated C/C++ note and replaced ambiguous labels.

* Reformat source with clang v10.0.1.

* Added the VFL technical note.

* Added what I believe might be called version 1.0 of the format.

* Added the remaining specs.

* Added H5Z callback documentation and fixed a few mistakes.

* Added dox for deprecated H5G calls and fixed a few snippet blockIDs.

* clang-format happy?

* Ok?

* Bonus track: Deprecated H5D functions.

* Carry over the more detailed group description.

* Added documentation for the missing and deprecated H5R calls.

* Life is easier and less repetitive w/ snippets. Use them!

* Eliminate the snippet block ID artifacts in the HTML rendering.

* Fixed snippet HTML artifacts and added a few missing calls.

* Under 20 H5Ps to go!

* Almost complete!

* "This is a form of pedantry up with which I will not put." (Churchill)

* Let's not waste as much space on bulleted lists!

* First complete (?) draft of the Doxygen-based RM.

* Completeness check and minor fixes along the way.

* Pedantry.

* Adding missing H5FD calls checkpoint.

* Pedantry.

* More pedantry.

* Added H5Pset_fapl_log.

* First draft of H5ES.

* Fixed warnings.

* Prep. for map module.

* First cut of the map module.

* Pedantry.

* Possible H5F introduction.

* Fix the indentation.

* Pedantry.

* Ditto.

* Thanks to the reviewers for their comments.

* Added missing images.

* Line numbers are a distraction here.

* More examples, references, and clean-up. Don't repeat yourself!

* Clang pedantry.

* Ditto.

* More reviewer comments...

* Templatized references and cleaned up \todos.

* Committing clang-format changes

* Fixed MANIFEST.

* Addressed Quincey's comments. (OCPLs)

* Fixed a few more \todo items.

* Fixed more \todo items.

* Added attribute life cycle.

* Forgot the examples file.

* Committing clang-format changes

* Pedantry.

* Live and learn!

* Added a sample H5D life cycle.

* Committing clang-format changes

* Pedantry.

Co-authored-by: kyang2014 <kyang2014@users.noreply.github.com>
Co-authored-by: Scot Breitenfeld <brtnfld@hdfgroup.org>
Co-authored-by: Kimmy Mu <kmu@hdfgroup.org>
Co-authored-by: Christopher Hogan <ChristopherHogan@users.noreply.github.com>
Co-authored-by: jya-kmu <53388330+jya-kmu@users.noreply.github.com>
Co-authored-by: David Young <dyoung@hdfgroup.org>
Co-authored-by: Larry Knox <lrknox@hdfgroup.org>
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

1 files changed, 224 insertions, 1 deletions

diff --git a/src/H5FDmpio.h b/src/H5FDmpio.h
index 79b52c7..8caf11c 100644
--- a/src/H5FDmpio.h
+++ b/src/H5FDmpio.h
@@ -44,14 +44,237 @@ H5_DLLVAR hbool_t H5FD_mpi_opt_types_g;
 #ifdef __cplusplus
 extern "C" {
 #endif
-H5_DLL hid_t  H5FD_mpio_init(void);
+H5_DLL hid_t H5FD_mpio_init(void);
+
+/**
+ * \ingroup FAPL
+ *
+ * \brief Stores MPI IO communicator information to the file access property list
+ *
+ * \fapl_id
+ * \param[in] comm MPI-2 communicator
+ * \param[in] info MPI-2 info object
+ * \returns \herr_t
+ *
+ * \details H5Pset_fapl_mpio() stores the user-supplied MPI IO parameters \p
+ *          comm, for communicator, and \p info, for information, in the file
+ *          access property list \p fapl_id. That property list can then be used
+ *          to create and/or open a file.
+ *
+ *          H5Pset_fapl_mpio() is available only in the parallel HDF5 library
+ *          and is not a collective function.
+ *
+ *          \p comm is the MPI communicator to be used for file open, as defined
+ *          in \c MPI_File_open of MPI-2. This function makes a duplicate of the
+ *          communicator, so modifications to \p comm after this function call
+ *          returns have no effect on the file access property list.
+ *
+ *          \p info is the MPI Info object to be used for file open, as defined
+ *          in MPI_File_open() of MPI-2. This function makes a duplicate copy of
+ *          the Info object, so modifications to the Info object after this
+ *          function call returns will have no effect on the file access
+ *          property list.
+ *
+ *          If the file access property list already contains previously-set
+ *          communicator and Info values, those values will be replaced and the
+ *          old communicator and Info object will be freed.
+ *
+ * \note Raw dataset chunk caching is not currently supported when using this
+ *       file driver in read/write mode. All calls to H5Dread() and H5Dwrite()
+ *       will access the disk directly, and H5Pset_cache() and
+ *       H5Pset_chunk_cache() will have no effect on performance.\n
+ *       Raw dataset chunk caching is supported when this driver is used in
+ *       read-only mode.
+ *
+ * \version 1.4.5 Handling of the MPI Communicator and Info object changed at
+ *          this release. A duplicate of each of these is now stored in the property
+ *          list instead of pointers to each.
+ * \since 1.4.0
+ *
+ */
 H5_DLL herr_t H5Pset_fapl_mpio(hid_t fapl_id, MPI_Comm comm, MPI_Info info);
+
+/**
+ * \ingroup FAPL
+ *
+ * \brief Returns MPI IO communicator information
+ *
+ * \fapl_id
+ * \param[out] comm MPI-2 communicator
+ * \param[out] info MPI-2 info object
+ * \returns \herr_t
+ *
+ * \details If the file access property list is set to the #H5FD_MPIO driver,
+ *          H5Pget_fapl_mpio() returns duplicates of the stored MPI communicator
+ *          and Info object through the \p comm and \p info pointers, if those
+ *          values are non-null.
+ *
+ *          Since the MPI communicator and Info object are duplicates of the
+ *          stored information, future modifications to the access property list
+ *          will not affect them. It is the responsibility of the application to
+ *          free these objects.
+ *
+ * \version 1.4.5 Handling of the MPI Communicator and Info object changed at
+ *          this release. A duplicate of each of these is now stored in the
+ *          property list instead of pointers to each.
+ * \since 1.4.0
+ *
+ */
 H5_DLL herr_t H5Pget_fapl_mpio(hid_t fapl_id, MPI_Comm *comm /*out*/, MPI_Info *info /*out*/);
+
+/**
+ * \ingroup DXPL
+ *
+ * \brief Sets data transfer mode
+ *
+ * \dxpl_id
+ * \param[in] xfer_mode Transfer mode
+ * \returns \herr_t
+ *
+ * \details H5Pset_dxpl_mpio() sets the data transfer property list \p dxpl_id
+ *          to use transfer mode \p 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.
+ *
+ * \since 1.4.0
+ *
+ */
 H5_DLL herr_t H5Pset_dxpl_mpio(hid_t dxpl_id, H5FD_mpio_xfer_t xfer_mode);
+
+/**
+ * \ingroup DXPL
+ *
+ * \brief Returns the data transfer mode
+ *
+ * \dxpl_id
+ * \param[out] xfer_mode Transfer mode
+ * \returns \herr_t
+ *
+ * \details H5Pget_dxpl_mpio() queries the data transfer mode currently set in
+ *          the data transfer property list \p dxpl_id.
+ *
+ *          Upon return, \p xfer_mode contains the data transfer mode, if it is
+ *          non-null.
+ *
+ *          H5Pget_dxpl_mpio() is not a collective function.
+ *
+ * \since 1.4.0
+ *
+ */
 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
+ *
+ * \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.
+ *
+ * \since 1.4.0
+ *
+ */
 H5_DLL herr_t H5Pset_dxpl_mpio_collective_opt(hid_t dxpl_id, H5FD_mpio_collective_opt_t opt_mode);
+
+/**
+ * \ingroup DXPL
+ *
+ * \brief Sets a flag specifying linked-chunk I/O or multi-chunk I/O
+ *
+ * \dxpl_id
+ * \param[in] opt_mode Transfer mode
+ * \returns \herr_t
+ *
+ * \details H5Pset_dxpl_mpio_chunk_opt() specifies whether I/O is to be
+ *          performed as linked-chunk I/O or as multi-chunk I/O. This function
+ *          overrides the HDF5 library's internal algorithm for determining
+ *          which mechanism to use.
+ *
+ *          When an application uses collective I/O with chunked storage, the
+ *          HDF5 library normally uses an internal algorithm to determine
+ *          whether that I/O activity should be conducted as one linked-chunk
+ *          I/O or as multi-chunk I/O. H5Pset_dxpl_mpio_chunk_opt() is provided
+ *          so that an application can override the library's algorithm in
+ *          circumstances where the library might lack the information needed to
+ *          make an optimal decision.
+ *
+ *          H5Pset_dxpl_mpio_chunk_opt() works by setting one of the following
+ *          flags in the parameter \p opt_mode:
+ *          - #H5FD_MPIO_CHUNK_ONE_IO -	Do one-link chunked I/O
+ *          - #H5FD_MPIO_CHUNK_MULTI_IO - Do multi-chunked I/O
+ *
+ *          This function works by setting a corresponding property in the
+ *          dataset transfer property list \p dxpl_id.
+ *
+ *          The library performs I/O in the specified manner unless it
+ *          determines that the low-level MPI IO package does not support the
+ *          requested behavior; in such cases, the HDF5 library will internally
+ *          use independent I/O.
+ *
+ *          Use of this function is optional.
+ *
+ * \todo Add missing version information
+ *
+ */
 H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt(hid_t dxpl_id, H5FD_mpio_chunk_opt_t opt_mode);
+
+/**
+ * \ingroup DXPL
+ *
+ * \brief Sets a numeric threshold for linked-chunk I/O
+ *
+ * \dxpl_id
+ * \param[in] num_chunk_per_proc
+ * \returns \herr_t
+ *
+ * \details H5Pset_dxpl_mpio_chunk_opt_num() sets a numeric threshold for the
+ *          use of linked-chunk I/O.
+ *
+ *          The library will calculate the average number of chunks selected by
+ *          each process when doing collective access with chunked storage. If
+ *          the number is greater than the threshold set in \p
+ *          num_chunk_per_proc, the library will use linked-chunk I/O;
+ *          otherwise, a separate I/O process will be invoked for each chunk
+ *          (multi-chunk I/O).
+ *
+ * \todo Add missing version information
+ *
+ */
 H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_num(hid_t dxpl_id, unsigned num_chunk_per_proc);
+
+/**
+ * \ingroup DXPL
+ *
+ * \brief Sets a ratio threshold for collective I/O
+ *
+ * \dxpl_id
+ * \param[in] percent_num_proc_per_chunk
+ * \returns \herr_t
+ *
+ * \details H5Pset_dxpl_mpio_chunk_opt_ratio() sets a threshold for the use of
+ *          collective I/O based on the ratio of processes with collective
+ *          access to a dataset with chunked storage. The decision whether to
+ *          use collective I/O is made on a per-chunk basis.
+ *
+ *          The library will calculate the percentage of the total number of
+ *          processes, the ratio, that hold selections in each chunk. If that
+ *          percentage is greater than the threshold set in \p
+ *          percent_proc_per_chunk, the library will do collective I/O for this
+ *          chunk; otherwise, independent I/O will be done for the chunk.
+ *
+ * \todo Add missing version information
+ *
+ */
 H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_ratio(hid_t dxpl_id, unsigned percent_num_proc_per_chunk);
 #ifdef __cplusplus
 }