From 58ef7dcdc9bfbfc65fe69d782914671f66322d85 Mon Sep 17 00:00:00 2001
From: Dana Robinson <43805+derobins@users.noreply.github.com>
Date: Mon, 30 Oct 2023 09:13:54 -0700
Subject: [PATCH] Update Doxygen initializers & identifiers in VFDs (#3795)

* Add Doxygen for all H5FD_<VFD> initializers
* Add Doxygen for all H5FD_<VFD>_VALUE values
* Mark H5FD_<vfd>_init() calls private in Doxygen
---
 src/H5FDcore.h     | 12 ++++++++++--
 src/H5FDdirect.h   | 33 +++++++++++++++++++++++++--------
 src/H5FDfamily.h   | 11 +++++++++--
 src/H5FDhdfs.h     | 21 ++++++++++++++++++---
 src/H5FDlog.h      | 11 +++++++++--
 src/H5FDmirror.h   | 11 +++++++++--
 src/H5FDmpio.h     | 25 ++++++++++++++++---------
 src/H5FDmulti.h    |  8 +++++++-
 src/H5FDonion.h    | 17 ++++++++++-------
 src/H5FDros3.h     | 20 ++++++++++++--------
 src/H5FDsec2.h     | 13 ++++++++++---
 src/H5FDsplitter.h | 12 ++++++++++--
 src/H5FDstdio.h    | 14 ++++++++++++--
 src/H5FDwindows.h  |  7 ++++++-
 14 files changed, 163 insertions(+), 52 deletions(-)

diff --git a/src/H5FDcore.h b/src/H5FDcore.h
index 235d6fcaaf7..cd45c8d6061 100644
--- a/src/H5FDcore.h
+++ b/src/H5FDcore.h
@@ -11,17 +11,25 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 /*
- * Purpose:	The public header file for the core driver.
+ * Purpose:	The public header file for the core virtual file driver (VFD)
  */
 #ifndef H5FDcore_H
 #define H5FDcore_H
 
-#define H5FD_CORE       (H5FDperform_init(H5FD_core_init))
+/** Initializer for the core VFD */
+#define H5FD_CORE (H5FDperform_init(H5FD_core_init))
+
+/** Identifier for the core VFD */
 #define H5FD_CORE_VALUE H5_VFD_CORE
 
 #ifdef __cplusplus
 extern "C" {
 #endif
+
+/** @private
+ *
+ * \brief Private initializer for the core VFD
+ */
 H5_DLL hid_t H5FD_core_init(void);
 
 /**
diff --git a/src/H5FDdirect.h b/src/H5FDdirect.h
index e47ac37cdea..1e60bb08119 100644
--- a/src/H5FDdirect.h
+++ b/src/H5FDdirect.h
@@ -11,30 +11,47 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 /*
- * Purpose:	The public header file for the direct driver.
+ * Purpose:	The public header file for the direct virtual file driver (VFD)
  */
 #ifndef H5FDdirect_H
 #define H5FDdirect_H
 
 #ifdef H5_HAVE_DIRECT
-#define H5FD_DIRECT       (H5FDperform_init(H5FD_direct_init))
+
+/** Initializer for the direct VFD */
+#define H5FD_DIRECT (H5FDperform_init(H5FD_direct_init))
+
+/** Identifier for the direct VFD */
 #define H5FD_DIRECT_VALUE H5_VFD_DIRECT
+
 #else
+
+/** Initializer for the direct VFD (disabled) */
 #define H5FD_DIRECT       (H5I_INVALID_HID)
+
+/** Identifier for the direct VFD (disabled) */
 #define H5FD_DIRECT_VALUE H5_VFD_INVALID
+
 #endif /* H5_HAVE_DIRECT */
 
+/** Default value for memory boundary */
+#define MBOUNDARY_DEF 4096
+
+/** Default value for file block size */
+#define FBSIZE_DEF 4096
+
+/** Default value for maximum copy buffer size */
+#define CBSIZE_DEF (16 * 1024 * 1024)
+
 #ifdef H5_HAVE_DIRECT
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/* Default values for memory boundary, file block size, and maximal copy buffer size.
- * Application can set these values through the function H5Pset_fapl_direct. */
-#define MBOUNDARY_DEF 4096
-#define FBSIZE_DEF    4096
-#define CBSIZE_DEF    16 * 1024 * 1024
-
+/** @private
+ *
+ * \brief Private initializer for the direct VFD
+ */
 H5_DLL hid_t H5FD_direct_init(void);
 
 /**
diff --git a/src/H5FDfamily.h b/src/H5FDfamily.h
index 76020f0a268..32e885c422d 100644
--- a/src/H5FDfamily.h
+++ b/src/H5FDfamily.h
@@ -11,18 +11,25 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 /*
- * Purpose:	The public header file for the family driver.
+ * Purpose:	The public header file for the family virtual file driver (VFD)
  */
 #ifndef H5FDfamily_H
 #define H5FDfamily_H
 
-#define H5FD_FAMILY       (H5FDperform_init(H5FD_family_init))
+/** Initializer for the family VFD */
+#define H5FD_FAMILY (H5FDperform_init(H5FD_family_init))
+
+/** Identifier for the family VFD */
 #define H5FD_FAMILY_VALUE H5_VFD_FAMILY
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/** @private
+ *
+ * \brief Private initializer for the family VFD
+ */
 H5_DLL hid_t H5FD_family_init(void);
 
 /**
diff --git a/src/H5FDhdfs.h b/src/H5FDhdfs.h
index c8c2c37f1b5..e5f7173fce2 100644
--- a/src/H5FDhdfs.h
+++ b/src/H5FDhdfs.h
@@ -11,18 +11,29 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 /*
- * Purpose:    The public header file for the hdfs driver.
+ * Purpose: The public header file for the Hadoop Distributed File System
+ *          (hdfs) virtual file driver (VFD)
  */
 
 #ifndef H5FDhdfs_H
 #define H5FDhdfs_H
 
 #ifdef H5_HAVE_LIBHDFS
-#define H5FD_HDFS       (H5FDperform_init(H5FD_hdfs_init))
+
+/** Initializer for the hdfs VFD */
+#define H5FD_HDFS (H5FDperform_init(H5FD_hdfs_init))
+
+/** Identifier for the hdfs VFD */
 #define H5FD_HDFS_VALUE H5_VFD_HDFS
-#else /* H5_HAVE_LIBHDFS */
+
+#else
+
+/** Initializer for the hdfs VFD (disabled) */
 #define H5FD_HDFS       (H5I_INVALID_HID)
+
+/** Identifier for the hdfs VFD (disabled) */
 #define H5FD_HDFS_VALUE H5_VFD_INVALID
+
 #endif /* H5_HAVE_LIBHDFS */
 
 #ifdef H5_HAVE_LIBHDFS
@@ -104,6 +115,10 @@ typedef struct H5FD_hdfs_fapl_t {
     int32_t stream_buffer_size;
 } H5FD_hdfs_fapl_t;
 
+/** @private
+ *
+ * \brief Private initializer for the hdfs VFD
+ */
 H5_DLL hid_t H5FD_hdfs_init(void);
 
 /**
diff --git a/src/H5FDlog.h b/src/H5FDlog.h
index ae4e2d05e72..b4af2050a62 100644
--- a/src/H5FDlog.h
+++ b/src/H5FDlog.h
@@ -11,12 +11,15 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 /*
- * Purpose:	The public header file for the log driver.
+ * Purpose:	The public header file for the log virtual file driver (VFD)
  */
 #ifndef H5FDlog_H
 #define H5FDlog_H
 
-#define H5FD_LOG       (H5FDperform_init(H5FD_log_init))
+/** Initializer for the log VFD */
+#define H5FD_LOG (H5FDperform_init(H5FD_log_init))
+
+/** Identifier for the log VFD */
 #define H5FD_LOG_VALUE H5_VFD_LOG
 
 /* Flags for H5Pset_fapl_log() */
@@ -62,6 +65,10 @@
 extern "C" {
 #endif
 
+/** @private
+ *
+ * \brief Private initializer for the log VFD
+ */
 H5_DLL hid_t H5FD_log_init(void);
 
 /**
diff --git a/src/H5FDmirror.h b/src/H5FDmirror.h
index b196b2b1adc..6c98e1a8a6f 100644
--- a/src/H5FDmirror.h
+++ b/src/H5FDmirror.h
@@ -11,7 +11,7 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 /*
- * Purpose: Public, shared definitions for Mirror VFD & remote Writer.
+ * Purpose:	The public header file for the mirror virtual file driver (VFD)
  */
 
 #ifndef H5FDmirror_H
@@ -19,7 +19,10 @@
 
 #ifdef H5_HAVE_MIRROR_VFD
 
-#define H5FD_MIRROR       (H5FDperform_init(H5FD_mirror_init))
+/** Initializer for the mirror VFD */
+#define H5FD_MIRROR (H5FDperform_init(H5FD_mirror_init))
+
+/** Identifier for the mirror VFD */
 #define H5FD_MIRROR_VALUE H5_VFD_MIRROR
 
 #ifdef __cplusplus
@@ -62,6 +65,10 @@ typedef struct H5FD_mirror_fapl_t {
     char     remote_ip[H5FD_MIRROR_MAX_IP_LEN + 1];
 } H5FD_mirror_fapl_t;
 
+/** @private
+ *
+ * \brief Private initializer for the mirror VFD
+ */
 H5_DLL hid_t H5FD_mirror_init(void);
 
 /**
diff --git a/src/H5FDmpio.h b/src/H5FDmpio.h
index 60deec2c07b..5e7ecf30353 100644
--- a/src/H5FDmpio.h
+++ b/src/H5FDmpio.h
@@ -11,35 +11,42 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 /*
- * Purpose:	The public header file for the mpio driver.
+ * Purpose:	The public header file for the MPI-I/O (mpio) virtual file driver (VFD)
  */
 #ifndef H5FDmpio_H
 #define H5FDmpio_H
 
-/* Macros */
-
 #ifdef H5_HAVE_PARALLEL
+
+/** Initializer for the mpio VFD */
 #define H5FD_MPIO (H5FDperform_init(H5FD_mpio_init))
+
 #else
+
+/** Initializer for the mpio VFD (disabled) */
 #define H5FD_MPIO (H5I_INVALID_HID)
-#endif /* H5_HAVE_PARALLEL */
+
+#endif
 
 #ifdef H5_HAVE_PARALLEL
-/*Turn on H5FDmpio_debug if H5F_DEBUG is on */
-#ifdef H5F_DEBUG
-#ifndef H5FDmpio_DEBUG
+
+#if defined(H5F_DEBUG) && !defined(H5FDmpio_DEBUG)
+/** Turn mpio VFD debugging on (requires H5F_DEBUG) */
 #define H5FDmpio_DEBUG
 #endif
-#endif
 
 /* Global var whose value comes from environment variable */
 /* (Defined in H5FDmpio.c) */
 H5_DLLVAR hbool_t H5FD_mpi_opt_types_g;
 
-/* Function prototypes */
 #ifdef __cplusplus
 extern "C" {
 #endif
+
+/** @private
+ *
+ * \brief Private initializer for the mpio VFD
+ */
 H5_DLL hid_t H5FD_mpio_init(void);
 
 /**
diff --git a/src/H5FDmulti.h b/src/H5FDmulti.h
index a85f2dfed25..d89a3e27cce 100644
--- a/src/H5FDmulti.h
+++ b/src/H5FDmulti.h
@@ -11,16 +11,22 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 /*
- * Purpose:	The public header file for the "multi" driver.
+ * Purpose:	The public header file for the multi virtual file driver (VFD)
  */
 #ifndef H5FDmulti_H
 #define H5FDmulti_H
 
+/** Initializer for the multi VFD */
 #define H5FD_MULTI (H5FDperform_init(H5FD_multi_init))
 
 #ifdef __cplusplus
 extern "C" {
 #endif
+
+/** @private
+ *
+ * \brief Private initializer for the multi VFD
+ */
 H5_DLL hid_t H5FD_multi_init(void);
 
 /**
diff --git a/src/H5FDonion.h b/src/H5FDonion.h
index 09b290e2a9e..4aaab6d3c3e 100644
--- a/src/H5FDonion.h
+++ b/src/H5FDonion.h
@@ -11,19 +11,18 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 /*
- * Onion Virtual File Driver (VFD)
- *
- * Purpose:    The public header file for the Onion VFD.
+ * Purpose:	The public header file for the onion virtual file driver (VFD)
  */
 #ifndef H5FDonion_H
 #define H5FDonion_H
 
-#define H5FD_ONION       (H5FDperform_init(H5FD_onion_init))
+/** Initializer for the onion VFD */
+#define H5FD_ONION (H5FDperform_init(H5FD_onion_init))
+
+/** Identifier for the onion VFD */
 #define H5FD_ONION_VALUE H5_VFD_ONION
 
-/**
- *  Current version of the onion VFD fapl info struct.
- */
+/** Current version of the onion VFD fapl info struct */
 #define H5FD_ONION_FAPL_INFO_VERSION_CURR 1
 
 #define H5FD_ONION_FAPL_INFO_CREATE_FLAG_ENABLE_PAGE_ALIGNMENT                                               \
@@ -114,6 +113,10 @@ typedef struct H5FD_onion_fapl_info_t {
 extern "C" {
 #endif
 
+/** @private
+ *
+ * \brief Private initializer for the onion VFD
+ */
 H5_DLL hid_t H5FD_onion_init(void);
 
 /**
diff --git a/src/H5FDros3.h b/src/H5FDros3.h
index ecd26789cc8..217af2d01b6 100644
--- a/src/H5FDros3.h
+++ b/src/H5FDros3.h
@@ -11,20 +11,24 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 /*
- * Read-Only S3 Virtual File Driver (VFD)
- *
- * Purpose:    The public header file for the ros3 driver.
+ * Purpose:	The public header file for the read-only S3 (ros3) virtual file driver (VFD)
  */
 #ifndef H5FDros3_H
 #define H5FDros3_H
 
 #ifdef H5_HAVE_ROS3_VFD
-#define H5FD_ROS3       (H5FDperform_init(H5FD_ros3_init))
+/** Initializer for the ros3 VFD */
+#define H5FD_ROS3 (H5FDperform_init(H5FD_ros3_init))
+
+/** Identifier for the ros3 VFD */
 #define H5FD_ROS3_VALUE H5_VFD_ROS3
 #else
+/** Initializer for the ros3 VFD (disabled) */
 #define H5FD_ROS3       (H5I_INVALID_HID)
+
+/** Identifier for the ros3 VFD (disabled) */
 #define H5FD_ROS3_VALUE H5_VFD_INVALID
-#endif /* H5_HAVE_ROS3_VFD */
+#endif
 
 #ifdef H5_HAVE_ROS3_VFD
 
@@ -139,9 +143,9 @@ typedef struct H5FD_ros3_fapl_t {
 extern "C" {
 #endif
 
-/**
- * \brief Internal routine to initialize #H5FD_ROS3 driver. Not meant to be
- *        called directly by an HDF5 application.
+/** @private
+ *
+ * \brief Private initializer for the ros3 VFD
  */
 H5_DLL hid_t H5FD_ros3_init(void);
 
diff --git a/src/H5FDsec2.h b/src/H5FDsec2.h
index a2590aee968..dd0a4d8918d 100644
--- a/src/H5FDsec2.h
+++ b/src/H5FDsec2.h
@@ -11,18 +11,26 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 /*
- * Purpose:	The public header file for the sec2 driver
+ * Purpose:	The public header file for the POSOX I/O (sec2 - "POSIX section 2")
+ *          virtual file driver (VFD)
  */
 #ifndef H5FDsec2_H
 #define H5FDsec2_H
 
-#define H5FD_SEC2       (H5FDperform_init(H5FD_sec2_init))
+/** Initializer for the sec2 VFD */
+#define H5FD_SEC2 (H5FDperform_init(H5FD_sec2_init))
+
+/** Identifier for the sec2 VFD */
 #define H5FD_SEC2_VALUE H5_VFD_SEC2
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/** @private
+ *
+ * \brief Private initializer for the sec2 VFD
+ */
 H5_DLL hid_t H5FD_sec2_init(void);
 
 /**
@@ -38,7 +46,6 @@ H5_DLL hid_t H5FD_sec2_init(void);
  *          #H5FD_SEC2 driver.
  *
  * \since 1.4.0
- *
  */
 H5_DLL herr_t H5Pset_fapl_sec2(hid_t fapl_id);
 
diff --git a/src/H5FDsplitter.h b/src/H5FDsplitter.h
index 8e790e212b6..99a471e5ce3 100644
--- a/src/H5FDsplitter.h
+++ b/src/H5FDsplitter.h
@@ -11,13 +11,16 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 /*
- * Purpose:	The public header file for the "splitter" driver.
+ * Purpose:	The public header file for the splitter virtual file driver (VFD)
  */
 
 #ifndef H5FDsplitter_H
 #define H5FDsplitter_H
 
-#define H5FD_SPLITTER       (H5FDperform_init(H5FD_splitter_init))
+/** Initializer for the splitter VFD */
+#define H5FD_SPLITTER (H5FDperform_init(H5FD_splitter_init))
+
+/** Identifier for the splitter VFD */
 #define H5FD_SPLITTER_VALUE H5_VFD_SPLITTER
 
 /** The version of the H5FD_splitter_vfd_config_t structure used */
@@ -55,6 +58,11 @@ typedef struct H5FD_splitter_vfd_config_t {
 #ifdef __cplusplus
 extern "C" {
 #endif
+
+/** @private
+ *
+ * \brief Private initializer for the splitter VFD
+ */
 H5_DLL hid_t H5FD_splitter_init(void);
 
 /**
diff --git a/src/H5FDstdio.h b/src/H5FDstdio.h
index e2e05a77d64..794fe31bf61 100644
--- a/src/H5FDstdio.h
+++ b/src/H5FDstdio.h
@@ -11,20 +11,26 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 /*
- * Purpose:	The public header file for the C stdio driver
+ * Purpose:	The public header file for the C stdio virtual file driver (VFD)
  */
 #ifndef H5FDstdio_H
 #define H5FDstdio_H
 
 #include "H5Ipublic.h"
 
+/** Initializer for the stdio VFD */
 #define H5FD_STDIO (H5FDperform_init(H5FD_stdio_init))
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/** @private
+ *
+ * \brief Private initializer for the stdio VFD
+ */
 H5_DLL hid_t H5FD_stdio_init(void);
+
 /**
  * \ingroup FAPL
  *
@@ -34,7 +40,11 @@ H5_DLL hid_t H5FD_stdio_init(void);
  * \returns \herr_t
  *
  * \details H5Pset_fapl_stdio() modifies the file access property list to use
- *          the standard I/O driver, H5FDstdio().
+ *          the stdio VFD, which uses I/O calls from stdio.h.
+ *
+ * \note This VFD was designed to be a "demo" VFD that shows how to write
+ * your own VFD. Most applications should not use this VFD and should instead
+ * use the POSIX I/O VFD (sec2).
  *
  * \since 1.4.0
  *
diff --git a/src/H5FDwindows.h b/src/H5FDwindows.h
index 14f698580f8..673d1c93b59 100644
--- a/src/H5FDwindows.h
+++ b/src/H5FDwindows.h
@@ -11,11 +11,16 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 /*
- * Purpose: The public header file for the Windows driver
+ * Purpose:	The public header file for the Windows virtual file driver (VFD)
+ *
+ *          This VFD uses no Win32 API calls directly (though it may be
+ *          rewritten to do so in the future). It is currently defined to
+ *          be the sec2 VFD.
  */
 #ifndef H5FDwindows_H
 #define H5FDwindows_H
 
+/** Initializer for the Windows VFD */
 #define H5FD_WINDOWS (H5FD_sec2_init())
 
 #ifdef __cplusplus