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, 368 insertions, 5 deletions

diff --git a/src/H5Mpublic.h b/src/H5Mpublic.h
index 4d8bef4..e0be828 100644
--- a/src/H5Mpublic.h
+++ b/src/H5Mpublic.h
@@ -61,8 +61,12 @@ typedef enum H5VL_map_specific_t {
     H5VL_MAP_DELETE /* H5Mdelete                */
 } H5VL_map_specific_t;
 
-/* Callback for H5Miterate() */
+//! <!-- [H5M_iterate_t_snip] -->
+/**
+ * Callback for H5Miterate()
+ */
 typedef herr_t (*H5M_iterate_t)(hid_t map_id, const void *key, void *op_data);
+//! <!-- [H5M_iterate_t_snip] -->
 
 /********************/
 /* Public Variables */
@@ -81,38 +85,397 @@ extern "C" {
  */
 #ifdef H5_HAVE_MAP_API
 
+/**
+ * \ingroup H5M
+ *
+ * \brief Creates a map object
+ *
+ * \fgdta_loc_id
+ * \param[in] name Map object name
+ * \type_id{key_type_id}
+ * \type_id{val_type_id}
+ * \lcpl_id
+ * \mcpl_id
+ * \mapl_id
+ * \returns \hid_t{map object}
+ *
+ * \details H5Mcreate() creates a new map object for storing key-value
+ *          pairs. The in-file datatype for keys is defined by \p key_type_id
+ *          and the in-file datatype for values is defined by \p val_type_id. \p
+ *          loc_id specifies the location to create the the map object and \p
+ *          name specifies the name of the link to the map object relative to
+ *          \p loc_id.
+ *
+ * \since 1.13.0
+ *
+ */
 H5_DLL hid_t H5Mcreate(hid_t loc_id, const char *name, hid_t key_type_id, hid_t val_type_id, hid_t lcpl_id,
                        hid_t mcpl_id, hid_t mapl_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Mcreate}
+ */
 H5_DLL hid_t H5Mcreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
                              const char *name, hid_t key_type_id, hid_t val_type_id, hid_t lcpl_id,
                              hid_t mcpl_id, hid_t mapl_id, hid_t es_id);
+
+/**
+ * \ingroup H5M
+ *
+ * \brief
+ *
+ * \details
+ *
+ * \since 1.13.0
+ *
+ */
 H5_DLL hid_t H5Mcreate_anon(hid_t loc_id, hid_t key_type_id, hid_t val_type_id, hid_t mcpl_id, hid_t mapl_id);
+
+/**
+ * \ingroup H5M
+ *
+ * \brief Opens a map object
+ *
+ * \fgdta_loc_id{loc_id}
+ * \param[in] name Map object name relative to \p loc_id
+ * \mapl_id
+ * \returns \hid_t{map object}
+ *
+ * \details H5Mopen() finds a map object specified by \p name under the location
+ *          specified by \p loc_id. The map object should be close with
+ *          H5Mclose() when the application is not longer interested in
+ *          accessing it.
+ *
+ * \since 1.13.0
+ *
+ */
 H5_DLL hid_t H5Mopen(hid_t loc_id, const char *name, hid_t mapl_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Mopen}
+ */
 H5_DLL hid_t H5Mopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
                            const char *name, hid_t mapl_id, hid_t es_id);
+
+/**
+ * \ingroup H5M
+ *
+ * \brief Terminates access to a map object
+ *
+ * \map_id
+ * \returns \herr_t
+ *
+ * \details H5Mclose() closes access to a map object specified by \p map_id and
+ *          releases resources used by it.
+ *
+ *          It is illegal to subsequently use that same map identifier in calls
+ *          to other map functions.
+ *
+ * \since 1.13.0
+ *
+ */
 H5_DLL herr_t H5Mclose(hid_t map_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Mclose}
+ */
 H5_DLL herr_t H5Mclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t map_id,
                              hid_t es_id);
-H5_DLL hid_t  H5Mget_key_type(hid_t map_id);
-H5_DLL hid_t  H5Mget_val_type(hid_t map_id);
-H5_DLL hid_t  H5Mget_create_plist(hid_t map_id);
-H5_DLL hid_t  H5Mget_access_plist(hid_t map_id);
+
+/**
+ * \ingroup H5M
+ *
+ * \brief Gets key datatype for a map object
+ *
+ * \map_id
+ * \returns \hid_t{datatype}
+ *
+ * \details H5Mget_key_type() retrieves key datatype as stored in the file for a
+ *          map object specified by \p map_id and returns identifier for the
+ *          datatype.
+ *
+ * \since 1.13.0
+ *
+ */
+H5_DLL hid_t H5Mget_key_type(hid_t map_id);
+
+/**
+ * \ingroup H5M
+ *
+ * \brief Gets value datatype for a map object
+ *
+ * \map_id
+ * \returns \hid_t{datatype}
+ *
+ * \details H5Mget_val_type() retrieves value datatype as stored in the file for
+ *          a map object specified by \p map_id and returns identifier for the
+ *          datatype .
+ *
+ * \since 1.13.0
+ *
+ */
+H5_DLL hid_t H5Mget_val_type(hid_t map_id);
+
+/**
+ * \ingroup H5M
+ *
+ * \brief Gets creation property list for a map object
+ *
+ * \map_id
+ * \returns \hid_t{map creation property list}
+ *
+ * \details H5Mget_create_plist() returns an identifier for a copy of the
+ *          creation property list for a map object specified by \p map_id.
+ *
+ * \since 1.13.0
+ *
+ */
+H5_DLL hid_t H5Mget_create_plist(hid_t map_id);
+
+/**
+ * \ingroup H5M
+ *
+ * \brief Gets access property list for a map object
+ *
+ * \map_id
+ * \returns \hid_t{map access property list}
+ *
+ * \details H5Mget_access_plist() returns an identifier for a copy of the access
+ *          property list for a map object specified by \p map_id.
+ *
+ * \since 1.13.0
+ *
+ */
+H5_DLL hid_t H5Mget_access_plist(hid_t map_id);
+
+/**
+ * \ingroup H5M
+ *
+ * \brief Retrieves the number of key-value pairs in a map object
+ *
+ * \map_id
+ * \param[out] count The number of key-value pairs stored in the map object
+ * \dxpl_id
+ * \returns \herr_t
+ *
+ * \details H5Mget_count() retrieves the number of key-value pairs stored in a
+ *          map specified by map_id.
+ *
+ * \since 1.13.0
+ *
+ */
 H5_DLL herr_t H5Mget_count(hid_t map_id, hsize_t *count, hid_t dxpl_id);
+
+/**
+ * \ingroup H5M
+ *
+ * \brief Adds a key-value pair to a map object
+ *
+ * \map_id
+ * \type_id{key_mem_type_id}
+ * \param[in] key Pointer to key buffer
+ * \type_id{val_mem_type_id}
+ * \param[in] value Pointer to value buffer
+ * \dxpl_id
+ * \returns \herr_t
+ *
+ * \details H5Mput() adds a key-value pair to a map object specified by \p
+ *          map_id, or updates the value for the specified key if one was set
+ *          previously.
+ *
+ *          \p key_mem_type_id and \p val_mem_type_id specify the datatypes for
+ *          the provided key and value buffers, and if different from those used
+ *          to create the map object, the key and value will be internally
+ *          converted to the datatypes for the map object.
+ *
+ *          Any further options can be specified through the property list
+ *          \p dxpl_id.
+ *
+ * \since 1.13.0
+ *
+ */
 H5_DLL herr_t H5Mput(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id,
                      const void *value, hid_t dxpl_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Mput}
+ */
 H5_DLL herr_t H5Mput_async(const char *app_file, const char *app_func, unsigned app_line, hid_t map_id,
                            hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, const void *value,
                            hid_t dxpl_id, hid_t es_id);
+
+/**
+ * \ingroup H5M
+ *
+ * \brief Retrieves a key-value pair from a map object
+ *
+ * \map_id
+ * \type_id{key_mem_type_id}
+ * \param[in] key Pointer to key buffer
+ * \type_id{val_mem_type_id}
+ * \param[out] value Pointer to value buffer
+ * \dxpl_id
+ * \returns \herr_t
+ *
+ * \details H5Mget() retrieves from a map object specified by \p map_id, the
+ *          value associated with the provided key \p key. \p key_mem_type_id
+ *          and \p val_mem_type_id specify the datatypes for the provided key
+ *          and value buffers. If if the datatype specified by \p
+ *          key_mem_type_id is different from that used to create the map object
+ *          the key will be internally converted to the datatype for the map
+ *          object for the query, and if the datatype specified by \p
+ *          val_mem_type_id is different from that used to create the map object
+ *          the returned value will be converted to have a datatype as specified
+ *          by \p val_mem_type_id before the function returns.
+ *
+ *          Any further options can be specified through the property list
+ *          \p dxpl_id.
+ *
+ * \since 1.13.0
+ *
+ */
 H5_DLL herr_t H5Mget(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, void *value,
                      hid_t dxpl_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Mget}
+ */
 H5_DLL herr_t H5Mget_async(const char *app_file, const char *app_func, unsigned app_line, hid_t map_id,
                            hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, void *value,
                            hid_t dxpl_id, hid_t es_id);
+
+/**
+ * \ingroup H5M
+ *
+ * \brief Checks if provided key exists in a map object
+ *
+ * \map_id
+ * \type_id{key_mem_type_id}
+ * \param[in] key Pointer to key buffer
+ * \param[out] exists Pointer to a buffer to return the existence status
+ * \dxpl_id
+ * \returns \herr_t
+ *
+ * \details H5Mexists() checks if the provided key is stored in the map object
+ *          specified by \p map_id. If \p key_mem_type_id is different from that
+ *          used to create the map object the key will be internally converted
+ *          to the datatype for the map object for the query.
+ *
+ *          Any further options can be specified through the property list
+ *          \p dxpl_id.
+ *
+ * \since 1.13.0
+ *
+ */
 H5_DLL herr_t H5Mexists(hid_t map_id, hid_t key_mem_type_id, const void *key, hbool_t *exists, hid_t dxpl_id);
+
+/**
+ * \ingroup H5M
+ *
+ * \brief Iterates over all key-value pairs in a map object
+ *
+ * \map_id
+ * \param[in,out] idx iteration index
+ * \type_id{key_mem_type_id}
+ * \param[in] op User-defined iterator function
+ * \op_data
+ * \dxpl_id
+ * \returns \herr_t
+ *
+ * \details H5Miterate() iterates over all key-value pairs stored in the map
+ *          object specified by \p map_id, making the callback specified by \p
+ *          op for each. The \p idx parameter is an in/out parameter that may be
+ *          used to restart a previously interrupted iteration. At the start of
+ *          iteration \p idx should be set to 0, and to restart iteration at the
+ *          same location on a subsequent call to H5Miterate(), \p idx should be
+ *          the same value as returned by the previous call. Iterate callback is
+ *          defined as:
+ *          \snippet this H5M_iterate_t_snip
+ *          The \p key parameter is the buffer for the key for this iteration,
+ *          converted to the datatype specified by \p key_mem_type_id. The \p
+ *          op_data parameter is a simple pass through of the value passed to
+ *          H5Miterate(), which can be used to store application-defined data for
+ *          iteration. A negative return value from this function will cause
+ *          H5Miterate() to issue an error, while a positive return value will
+ *          cause H5Miterate() to stop iterating and return this value without
+ *          issuing an error. A return value of zero allows iteration to continue.
+ *
+ *          Any further options can be specified through the property list \p dxpl_id.
+ *
+ * \since 1.13.0
+ *
+ */
 H5_DLL herr_t H5Miterate(hid_t map_id, hsize_t *idx, hid_t key_mem_type_id, H5M_iterate_t op, void *op_data,
                          hid_t dxpl_id);
+
+/**
+ * \ingroup H5M
+ *
+ * \brief Iterates over all key-value pairs in a map object
+ *
+ * \loc_id
+ * \param[in] map_name Map object name relative to the location specified by \p loc_id
+ * \param[in,out] idx Iteration index
+ * \type_id{key_mem_type_id}
+ * \param[in] op User-defined iterator function
+ * \op_data
+ * \dxpl_id
+ * \lapl_id
+ * \returns \herr_t
+ *
+ * \details H5Miterate_by_name() iterates over all key-value pairs stored in the
+ *          map object specified by \p map_id, making the callback specified by
+ *          \p op for each. The \p idx parameter is an in/out parameter that may
+ *          be used to restart a previously interrupted iteration. At the start
+ *          of iteration \p idx should be set to 0, and to restart iteration at
+ *          the same location on a subsequent call to H5Miterate(), \p idx
+ *          should be the same value as returned by the previous call. Iterate
+ *          callback is defined as:
+ *          \snippet this H5M_iterate_t_snip
+ *          The\p key parameter is the buffer for the key for this iteration,
+ *          converted to the datatype specified by \p key_mem_type_id. The \p
+ *          op_data parameter is a simple pass through of the value passed to
+ *          H5Miterate(), which can be used to store application-defined data
+ *          for iteration. A negative return value from this function will cause
+ *          H5Miterate() to issue an error, while a positive return value will cause
+ *          H5Miterate() to stop iterating and return this value without issuing an
+ *          error. A return value of zero allows iteration to continue.
+ *
+ *          Any further options can be specified through the property list \p dxpl_id.
+ *
+ * \since 1.13.0
+ *
+ */
 H5_DLL herr_t H5Miterate_by_name(hid_t loc_id, const char *map_name, hsize_t *idx, hid_t key_mem_type_id,
                                  H5M_iterate_t op, void *op_data, hid_t dxpl_id, hid_t lapl_id);
+
+/**
+ * \ingroup H5M
+ *
+ * \brief Deletes a key-value pair from a map object
+ *
+ * \map_id
+ * \type_id{key_mem_type_id}
+ * \param[in] key Pointer to key buffer
+ * \dxpl_id
+ * \returns \herr_t
+ *
+ * \details H5Mdelete() deletes a key-value pair from the map object specified
+ *          by \p map_id. \p key_mem_type_id specifies the datatype for the
+ *          provided key buffer key, and if different from that used to create
+ *          the map object, the key will be internally converted to the datatype
+ *          for the map object.
+ *
+ *          Any further options can be specified through the property list \p dxpl_id.
+ *
+ * \since 1.13.0
+ *
+ */
 H5_DLL herr_t H5Mdelete(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t dxpl_id);
 
 /* API Wrappers for async routines */