From ac9541100f1067a60292dca09bc41fc0649537b5 Mon Sep 17 00:00:00 2001
From: Dana Robinson <43805+derobins@users.noreply.github.com>
Date: Sun, 10 Mar 2024 17:26:14 -0700
Subject: Add Doxygen for HDFS VFD (#4106)

* Add Doxygen for HDFS VFD

* Fix Doxygen warning

* Update H5FDhdfs.h
---
 src/H5FDhdfs.h | 121 ++++++++++++++++++++++++++++-----------------------------
 1 file changed, 59 insertions(+), 62 deletions(-)

diff --git a/src/H5FDhdfs.h b/src/H5FDhdfs.h
index e5f7173..3150a45 100644
--- a/src/H5FDhdfs.h
+++ b/src/H5FDhdfs.h
@@ -41,71 +41,49 @@
 extern "C" {
 #endif
 
-/****************************************************************************
- *
- * Structure: H5FD_hdfs_fapl_t
- *
- * Purpose:
- *
- *     H5FD_hdfs_fapl_t is a public structure that is used to pass
- *     configuration information to the appropriate HDFS VFD via the FAPL.
- *     A pointer to an instance of this structure is a parameter to
- *     H5Pset_fapl_hdfs() and H5Pget_fapl_hdfs().
- *
- *
- *
- * `version` (int32_t)
- *
- *     Version number of the `H5FD_hdfs_fapl_t` structure.  Any instance passed
- *     to the above calls must have a recognized version number, or an error
- *     will be flagged.
- *
- *     This field should be set to `H5FD__CURR_HDFS_FAPL_T_VERSION`.
- *
- * `namenode_name` (const char[])
- *
- *     Name of "Name Node" to access as the HDFS server.
- *
- *     Must not be longer than `H5FD__HDFS_NODE_NAME_SPACE`.
- *
- *     TBD: Can be NULL.
- *
- * `namenode_port` (int32_t) TBD
- *
- *     Port number to use to connect with Name Node.
- *
- *     TBD: If 0, uses a default port.
- *
- * `kerberos_ticket_cache` (const char[])
- *
- *     Path to the location of the Kerberos authentication cache.
- *
- *     Must not be longer than `H5FD__HDFS_KERB_CACHE_PATH_SPACE`.
- *
- *     TBD: Can be NULL.
- *
- * `user_name` (const char[])
+/**
+ * The version number of the H5FD_hdfs_fapl_t configuration
+ * structure for the #H5FD_HDFS driver
+ */
+#define H5FD__CURR_HDFS_FAPL_T_VERSION 1
+
+/** Max size of the node name */
+#define H5FD__HDFS_NODE_NAME_SPACE 128
+/** Max size of the user name */
+#define H5FD__HDFS_USER_NAME_SPACE 128
+/** Max size of the kerberos cache path */
+#define H5FD__HDFS_KERB_CACHE_PATH_SPACE 128
+
+/**
+ *\struct H5FD_hdfs_fapl_t
+ * \brief Configuration structure for H5Pset_fapl_hdfs() / H5Pget_fapl_hdfs()
  *
- *     Username to use when accessing file.
+ * \details H5FD_hdfs_fapl_t is a public structure that is used to pass
+ *          configuration data to the #H5FD_HDFS driver via a File Access
+ *          Property List. A pointer to an instance of this structure is
+ *          a parameter to H5Pset_fapl_hdfs() and H5Pget_fapl_hdfs().
  *
- *     Must not be longer than `H5FD__HDFS_USER_NAME_SPACE`.
+ * \var int32_t H5FD_hdfs_fapl_t::version
+ *      Version number of the H5FD_hdfs_fapl_t structure. Any instance passed
+ *      to H5Pset_fapl_hdfs() / H5Pget_fapl_hdfs() must have a recognized version
+ *      number or an error will be raised. Currently, this field should be set
+ *      to #H5FD__CURR_HDFS_FAPL_T_VERSION.
  *
- *     TBD: Can be NULL.
+ * \var char H5FD_hdfs_fapl_t::namenode_name[H5FD__HDFS_NODE_NAME_SPACE + 1]
+ *      Name of "Name Node" to access as the HDFS server
  *
- * `stream_buffer_size` (int32_t)
+ * \var int32_t H5FD_hdfs_fapl_t::namenode_port
+ *      Port number to use to connect with Name Node
  *
- *     Size (in bytes) of the file read stream buffer.
+ * \var char H5FD_hdfs_fapl_t::user_name[H5FD__HDFS_USER_NAME_SPACE + 1]
+ *      Username to use when accessing file
  *
- *     TBD: If -1, relies on a default value.
+ * \var char H5FD_hdfs_fapl_t::kerberos_ticket_cache[H5FD__HDFS_KERB_CACHE_PATH_SPACE + 1]
+ *      Path to the location of the Kerberos authentication cache
  *
- ****************************************************************************/
-
-#define H5FD__CURR_HDFS_FAPL_T_VERSION 1
-
-#define H5FD__HDFS_NODE_NAME_SPACE       128
-#define H5FD__HDFS_USER_NAME_SPACE       128
-#define H5FD__HDFS_KERB_CACHE_PATH_SPACE 128
-
+ * \var int32_t H5FD_hdfs_fapl_t::stream_buffer_size
+ *      Size (in bytes) of the file read stream buffer
+ */
 typedef struct H5FD_hdfs_fapl_t {
     int32_t version;
     char    namenode_name[H5FD__HDFS_NODE_NAME_SPACE + 1];
@@ -124,16 +102,35 @@ H5_DLL hid_t H5FD_hdfs_init(void);
 /**
  * \ingroup FAPL
  *
- * \todo Add missing documentation
+ * \brief Modifies the file access property list to use the #H5FD_HDFS driver
+ *
+ * \fapl_id
+ * \param[in] fa Pointer to #H5FD_HDFS driver configuration structure
+ *
+ * \returns \herr_t
+ *
+ * \details H5Pset_fapl_hdfs() modifies the file access property list to use the
+ *          #H5FD_HDFS driver.
+ *
+ * \since 1.10.6
  */
-H5_DLL herr_t H5Pget_fapl_hdfs(hid_t fapl_id, H5FD_hdfs_fapl_t *fa_out);
+H5_DLL herr_t H5Pset_fapl_hdfs(hid_t fapl_id, H5FD_hdfs_fapl_t *fa);
 
 /**
  * \ingroup FAPL
  *
- * \todo Add missing documentation
+ * \brief Queries a File Access Property List for #H5FD_HDFS file driver properties
+ *
+ * \fapl_id
+ * \param[out] fa_out Pointer to #H5FD_HDFS driver configuration structure
+ * \returns \herr_t
+ *
+ * \details H5Pget_fapl_hdfs() queries the #H5FD_HDFS driver properties as set
+ *          by H5Pset_fapl_hdfs().
+ *
+ * \since 1.10.6
  */
-H5_DLL herr_t H5Pset_fapl_hdfs(hid_t fapl_id, H5FD_hdfs_fapl_t *fa);
+H5_DLL herr_t H5Pget_fapl_hdfs(hid_t fapl_id, H5FD_hdfs_fapl_t *fa_out);
 
 #ifdef __cplusplus
 }
-- 
cgit v0.12