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

@@ -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);
 
 /**

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);
 
 /**

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);
 
 /**

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);
 
 /**

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);
 
 /**

src/H5FDmirror.h

@@ -11,15 +11,18 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 /*
- * Purpose: Public, shared definitions for Mirror VFD & remote Writer.
+ * Purpose:	The public header file for the mirror virtual file driver (VFD)
  */
 
 #ifndef H5FDmirror_H
 #define H5FDmirror_H
 
 #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);
 
 /**

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);
 
 /**

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);
 
 /**

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);
 
 /**

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);