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, 113 insertions, 37 deletions

diff --git a/src/H5public.h b/src/H5public.h
index b319550..751abbe 100644
--- a/src/H5public.h
+++ b/src/H5public.h
@@ -95,50 +95,130 @@ extern "C" {
 #define H5_NO_EXPAND(x) (x)
 
 /* Version numbers */
-#define H5_VERS_MAJOR      1  /* For major interface/format changes       */
-#define H5_VERS_MINOR      13 /* For minor interface/format changes       */
-#define H5_VERS_RELEASE    0  /* For tweaks, bug-fixes, or development    */
-#define H5_VERS_SUBRELEASE "" /* For pre-releases like snap0          */
-/* Empty string for real releases.           */
-#define H5_VERS_INFO "HDF5 library version: 1.13.0" /* Full version string */
+/**
+ * For major interface/format changes
+ */
+#define H5_VERS_MAJOR 1
+/**
+ * For minor interface/format changes
+ */
+#define H5_VERS_MINOR 13
+/**
+ * For tweaks, bug-fixes, or development
+ */
+#define H5_VERS_RELEASE 0
+/**
+ * For pre-releases like \c snap0. Empty string for official releases.
+ */
+#define H5_VERS_SUBRELEASE ""
+/**
+ * Full version string
+ */
+#define H5_VERS_INFO "HDF5 library version: 1.13.0"
 
 #define H5check() H5check_version(H5_VERS_MAJOR, H5_VERS_MINOR, H5_VERS_RELEASE)
 
 /* macros for comparing the version */
+/**
+ * \brief Determines whether the version of the library being used is greater
+ *        than or equal to the specified version
+ *
+ * \param[in] Maj Major version number - A non-negative integer value
+ * \param[in] Min Minor version number - A non-negative integer value
+ * \param[in] Rel Release version number - A non-negative integer value
+ * \returns A value of 1 is returned if the library version is greater than
+ *          or equal to the version number specified.\n
+ *          A value of 0 is returned if the library version is less than the
+ *          version number specified.\n
+ *          A library version is greater than the specified version number if
+ *          its major version is larger than the specified major version
+ *          number. If the major version numbers are the same, it is greater
+ *          than the specified version number if its minor version is larger
+ *          than the specified minor version number. If the minor version
+ *          numbers are the same, then a library version would be greater than
+ *          the specified version number if its release number is larger than
+ *          the specified release number.
+ *
+ * \details The #H5_VERSION_GE and #H5_VERSION_LE macros are used at compile
+ *          time to conditionally include or exclude code based on the version
+ *          of the HDF5 library against which an application will be linked.
+ *
+ *          The #H5_VERSION_GE macro compares the version of the HDF5 library
+ *          being used against the version number specified in the parameters.
+ *
+ *          For more information about release versioning, see \ref_h5lib_relver.
+ *
+ * \since 1.8.7
+ *
+ */
 #define H5_VERSION_GE(Maj, Min, Rel)                                                                         \
     (((H5_VERS_MAJOR == Maj) && (H5_VERS_MINOR == Min) && (H5_VERS_RELEASE >= Rel)) ||                       \
      ((H5_VERS_MAJOR == Maj) && (H5_VERS_MINOR > Min)) || (H5_VERS_MAJOR > Maj))
 
+/**
+ * \brief Determines whether the version of the library being used is less
+ *        than or equal to the specified version
+ *
+ * \param[in] Maj Major version number - A non-negative integer value
+ * \param[in] Min Minor version number - A non-negative integer value
+ * \param[in] Rel Release version number - A non-negative integer value
+ * \returns A value of 1 is returned if the library version is less than
+ *          or equal to the version number specified.\n
+ *          A value of 0 is returned if the library version is greater than the
+ *          version number specified.\n
+ *          A library version is less than the specified version number if
+ *          its major version is smaller than the specified major version
+ *          number. If the major version numbers are the same, it is smaller
+ *          than the specified version number if its minor version is smaller
+ *          than the specified minor version number. If the minor version
+ *          numbers are the same, then a library version would be smaller than
+ *          the specified version number if its release number is smaller than
+ *          the specified release number.
+ *
+ * \details The #H5_VERSION_GE and #H5_VERSION_LE macros are used at compile
+ *          time to conditionally include or exclude code based on the version
+ *          of the HDF5 library against which an application will be linked.
+ *
+ *          The #H5_VERSION_LE macro compares the version of the HDF5 library
+ *          being used against the version number specified in the parameters.
+ *
+ *          For more information about release versioning, see \ref_h5lib_relver.
+ *
+ * \since 1.8.7
+ *
+ */
 #define H5_VERSION_LE(Maj, Min, Rel)                                                                         \
     (((H5_VERS_MAJOR == Maj) && (H5_VERS_MINOR == Min) && (H5_VERS_RELEASE <= Rel)) ||                       \
      ((H5_VERS_MAJOR == Maj) && (H5_VERS_MINOR < Min)) || (H5_VERS_MAJOR < Maj))
 
-/*
+/**
  * Status return values.  Failed integer functions in HDF5 result almost
  * always in a negative value (unsigned failing functions sometimes return
  * zero for failure) while successful return is non-negative (often zero).
  * The negative failure value is most commonly -1, but don't bet on it.  The
  * proper way to detect failure is something like:
- *
- *  if((dset = H5Dopen2(file, name)) < 0)
- *      fprintf(stderr, "unable to open the requested dataset\n");
+ * \code
+ * if((dset = H5Dopen2(file, name)) < 0)
+ *    fprintf(stderr, "unable to open the requested dataset\n");
+ * \endcode
  */
 typedef int herr_t;
 
-/*
+/**
  * Boolean type.  Successful return values are zero (false) or positive
  * (true). The typical true value is 1 but don't bet on it.  Boolean
- * functions cannot fail.  Functions that return `htri_t' however return zero
+ * functions cannot fail.  Functions that return #htri_t however return zero
  * (false), positive (true), or negative (failure). The proper way to test
- * for truth from a htri_t function is:
- *
- *  if ((retval = H5Tcommitted(type)) > 0) {
- *      printf("data type is committed\n");
- *  } else if (!retval) {
- *      printf("data type is not committed\n");
- *  } else {
- *      printf("error determining whether data type is committed\n");
- *  }
+ * for truth from a #htri_t function is:
+ * \code
+ * if ((retval = H5Tcommitted(type)) > 0) {
+ *     printf("data type is committed\n");
+ * } else if (!retval) {
+ *     printf("data type is not committed\n");
+ * } else {
+ *     printf("error determining whether data type is committed\n");
+ * }
+ * \endcode
  */
 #ifdef H5_HAVE_STDBOOL_H
 #include <stdbool.h>
@@ -307,8 +387,7 @@ typedef unsigned long      uint32_t;
 #error "nothing appropriate for uint32_t"
 #endif
 
-//! [H5_iter_order_t_snip]
-
+//! <!-- [H5_iter_order_t_snip] -->
 /**
  * Common iteration orders
  */
@@ -319,8 +398,7 @@ typedef enum {
     H5_ITER_NATIVE,       /**< No particular order, whatever is fastest */
     H5_ITER_N             /**< Number of iteration orders */
 } H5_iter_order_t;
-
-//! [H5_iter_order_t_snip]
+//! <!-- [H5_iter_order_t_snip] -->
 
 /* Iteration callback values */
 /* (Actually, any positive value will cause the iterator to stop and pass back
@@ -330,8 +408,7 @@ typedef enum {
 #define H5_ITER_CONT  (0)
 #define H5_ITER_STOP  (1)
 
-//! [H5_index_t_snip]
-
+//! <!-- [H5_index_t_snip] -->
 /**
  * The types of indices on links in groups/attributes on objects.
  * Primarily used for "<do> <foo> by index" routines and for iterating over
@@ -343,18 +420,17 @@ typedef enum H5_index_t {
     H5_INDEX_CRT_ORDER,    /**< Index on creation order              */
     H5_INDEX_N             /**< Number of indices defined            */
 } H5_index_t;
-
-//! [H5_index_t_snip]
+//! <!-- [H5_index_t_snip] -->
 
 /**
  * Storage info struct used by H5O_info_t and H5F_info_t
  */
-//! [H5_ih_info_t_snip]
+//! <!-- [H5_ih_info_t_snip] -->
 typedef struct H5_ih_info_t {
     hsize_t index_size; /**< btree and/or list */
     hsize_t heap_size;
 } H5_ih_info_t;
-//! [H5_ih_info_t_snip]
+//! <!-- [H5_ih_info_t_snip] -->
 
 /**
  * The maximum size allowed for tokens
@@ -364,17 +440,17 @@ typedef struct H5_ih_info_t {
  */
 #define H5O_MAX_TOKEN_SIZE (16)
 
-//! [H5O_token_t_snip]
-
+//! <!-- [H5O_token_t_snip] -->
 /**
+ * Type for object tokens
+ *
  * \internal (Hoisted here, since it's used by both the
- *            H5Lpublic.h and H5Opublic.h headers) */
-/* Type for object tokens */
+ *            H5Lpublic.h and H5Opublic.h headers)
+ */
 typedef struct H5O_token_t {
     uint8_t __data[H5O_MAX_TOKEN_SIZE];
 } H5O_token_t;
-
-//! [H5O_token_t_snip]
+//! <!-- [H5O_token_t_snip] -->
 
 /**
  * Allocation statistics info struct