Add release information to enum constants - Part 1 (#5174)

* Add release information to enum constants - Part 1 - Added \since to enum constants added in 1.8.x versions - Removed unnecessary continuation backslashes in doxygen comments; they are displayed in the generated output.
HDFGroup · Dec 11, 2024 · d38baa4 · d38baa4
1 parent 44cff23
commit d38baa4
Show file tree

Hide file tree

Showing 7 changed files with 47 additions and 30 deletions.
diff --git a/src/H5FDhdfs.h b/src/H5FDhdfs.h
@@ -31,7 +31,7 @@
 
 #else
 
-/** Initializer for the hdfs VFD (disabled) */
+/** Initializer for the hdfs VFD (disabled) \since 1.8.22 */
 #define H5FD_HDFS       (H5I_INVALID_HID)
 
 /** Identifier for the hdfs VFD (disabled) */
@@ -47,11 +47,11 @@
  */
 #define H5FD__CURR_HDFS_FAPL_T_VERSION 1
 
-/** Max size of the node name */
+/** Max size of the node name \since 1.8.22 */
 #define H5FD__HDFS_NODE_NAME_SPACE 128
-/** Max size of the user name */
+/** Max size of the user name \since 1.8.22 */
 #define H5FD__HDFS_USER_NAME_SPACE 128
-/** Max size of the kerberos cache path */
+/** Max size of the kerberos cache path \since 1.8.22 */
 #define H5FD__HDFS_KERB_CACHE_PATH_SPACE 128
 
 /**

diff --git a/src/H5FDpublic.h b/src/H5FDpublic.h
@@ -107,18 +107,23 @@
  * of type 'int' and is compatible with POSIX I/O calls.
  */
 #define H5FD_FEAT_POSIX_COMPAT_HANDLE 0x00000080
-/*
- * Defining H5FD_FEAT_HAS_MPI for a VFL driver means that
- * the driver makes use of MPI communication and code may retrieve
- * communicator/rank information from it
- */
+
 #define H5FD_FEAT_HAS_MPI 0x00000100
-/*
- * Defining the H5FD_FEAT_ALLOCATE_EARLY for a VFL driver will force
- * the library to use the H5D_ALLOC_TIME_EARLY on dataset create
- * instead of the default H5D_ALLOC_TIME_LATE
+/**< Defining H5FD_FEAT_HAS_MPI for a VFL driver means that
+ *   the driver makes use of MPI communication and code may retrieve
+ *   communicator/rank information from it
+ *
+ * \since 1.8.15
  */
+
 #define H5FD_FEAT_ALLOCATE_EARLY 0x00000200
+/**< Defining the H5FD_FEAT_ALLOCATE_EARLY for a VFL driver will force
+ *   the library to use the H5D_ALLOC_TIME_EARLY on dataset create
+ *   instead of the default H5D_ALLOC_TIME_LATE
+ *
+ * \since 1.8.15
+ */
+
 /*
  * Defining H5FD_FEAT_ALLOW_FILE_IMAGE for a VFL driver means that
  * the driver is able to use a file image in the fapl as the initial

diff --git a/src/H5FDros3.h b/src/H5FDros3.h
@@ -21,17 +21,17 @@
 
 #ifdef H5_HAVE_ROS3_VFD
 
-/** ID for the ros3 VFD */
+/** Initializer for the ros3 VFD \since 1.8.22 */
 #define H5FD_ROS3 (H5OPEN H5FD_ROS3_id_g)
 
-/** Identifier for the ros3 VFD */
+/** Identifier for the ros3 VFD \since 1.14.0 */
 #define H5FD_ROS3_VALUE H5_VFD_ROS3
 
 #else
-/** Initializer for the ros3 VFD (disabled) */
+/** Initializer for the ros3 VFD (disabled) \since 1.8.22 */
 #define H5FD_ROS3       (H5I_INVALID_HID)
 
-/** Identifier for the ros3 VFD (disabled) */
+/** Identifier for the ros3 VFD (disabled) \since 1.14.0 */
 #define H5FD_ROS3_VALUE H5_VFD_INVALID
 #endif
 

diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h
@@ -32,13 +32,13 @@
 /* NOTE: 0x0008u was H5F_ACC_DEBUG, now deprecated */
 #define H5F_ACC_CREAT (0x0010u) /**< Create non-existing files  */
 #define H5F_ACC_SWMR_WRITE                                                                                   \
-    (0x0020u) /**< Indicate that this file is open for writing in a                                          \
+    (0x0020u) /**< Indicates that this file is open for writing in a                                         \
                *   single-writer/multi-reader (SWMR)  scenario.                                              \
                *   Note that the process(es) opening the file for reading                                    \
                *   must open the file with #H5F_ACC_RDONLY and use the                                       \
                *   #H5F_ACC_SWMR_READ access flag. */
 #define H5F_ACC_SWMR_READ                                                                                    \
-    (0x0040u) /**< Indicate that this file is open for reading in a                                          \
+    (0x0040u) /**< Indicates that this file is open for reading in a                                         \
                * single-writer/multi-reader (SWMR) scenario. Note that                                       \
                * the process(es) opening the file for SWMR reading must                                      \
                * also open the file with the #H5F_ACC_RDONLY flag.  */
@@ -231,9 +231,10 @@ typedef herr_t (*H5F_flush_cb_t)(hid_t object_id, void *udata);
                *   high number of unused bits.  See documentation for                                        \
                *   H5Pset_relax_file_integrity_checks for details. */
 #define H5F_RFIC_ALL                                                                                         \
-    (H5F_RFIC_UNUSUAL_NUM_UNUSED_NUMERIC_BITS) /**< Suppress all format integrity check errors.  See         \
-                                                *   documentation for H5Pset_relax_file_integrity_checks     \
-                                                *   for details. */
+    (H5F_RFIC_UNUSUAL_NUM_UNUSED_NUMERIC_BITS) /**< Suppress all format integrity check                      \
+                                                * errors.  See documentation for                             \
+                                                * H5Pset_relax_file_integrity_checks                         \
+                                                * for details. */
 
 /*********************/
 /* Public Prototypes */

diff --git a/src/H5PLpublic.h b/src/H5PLpublic.h
@@ -41,10 +41,16 @@ typedef enum H5PL_type_t {
 //! <!-- [H5PL_type_t_snip] -->
 
 /* Common dynamic plugin type flags used by the set/get_loading_state functions */
+/** Flag for filter plugin \since 1.8.15 */
 #define H5PL_FILTER_PLUGIN 0x0001
-#define H5PL_VOL_PLUGIN    0x0002
-#define H5PL_VFD_PLUGIN    0x0004
-#define H5PL_ALL_PLUGIN    0xFFFF
+/** Flag for VOL plugin \since 1.12.0 */
+#define H5PL_VOL_PLUGIN 0x0002
+/** Flag for VFD plugin \since 1.14.0 */
+#define H5PL_VFD_PLUGIN 0x0004
+/** Flag for all plugin types \since 1.8.15 */
+#define H5PL_ALL_PLUGIN 0xFFFF
+
+#define H5F_ACC_DEBUG (0x0000u) /**< Print debug info \deprecated In which version? */
 
 #ifdef __cplusplus
 extern "C" {

diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h
@@ -1012,7 +1012,7 @@ H5_DLL htri_t H5Pexist(hid_t plist_id, const char *name);
  *
  *          The property name must exist or this routine will fail.
  *
- *          If the \p get callback routine returns an error, \ value will
+ *          If the \p get callback routine returns an error, \p value will
  *          not be modified.
  *
  * \since 1.4.0

diff --git a/src/H5public.h b/src/H5public.h
@@ -343,10 +343,15 @@ typedef int64_t hssize_t;
  * \internal Defined as a (minimum) 64-bit unsigned integer type.
  */
 typedef uint64_t haddr_t;
-#define PRIdHADDR           PRId64
-#define PRIoHADDR           PRIo64
-#define PRIuHADDR           PRIu64
-#define PRIxHADDR           PRIx64
+/** d print conversion specifier \since 1.8.23 */
+#define PRIdHADDR PRId64
+/** o print conversion specifier \since 1.8.23 */
+#define PRIoHADDR PRIo64
+/** u print conversion specifier \since 1.8.23 */
+#define PRIuHADDR PRIu64
+/** x print conversion specifier \since 1.8.23 */
+#define PRIxHADDR PRIx64
+/** x print conversion specifier \since 1.8.23 */
 #define PRIXHADDR           PRIX64
 #define H5_SIZEOF_HADDR_T   8
 #define HADDR_UNDEF         UINT64_MAX