From aae5c26e53be083c145ae6ee79fffd9ffe25a7f8 Mon Sep 17 00:00:00 2001
From: Dana Robinson <43805+derobins@users.noreply.github.com>
Date: Sat, 16 Mar 2024 09:44:59 -0700
Subject: [PATCH] Add Doxygen to H5FDmirror.h (#4158)

---
 src/H5FDmirror.h | 77 ++++++++++++++++++++++++++++++++----------------
 1 file changed, 52 insertions(+), 25 deletions(-)

diff --git a/src/H5FDmirror.h b/src/H5FDmirror.h
index 6c98e1a8a6f..304f1e5a3f8 100644
--- a/src/H5FDmirror.h
+++ b/src/H5FDmirror.h
@@ -25,39 +25,43 @@
 /** Identifier for the mirror VFD */
 #define H5FD_MIRROR_VALUE H5_VFD_MIRROR
 
-#ifdef __cplusplus
-extern "C" {
-#endif
+/** Magic number to identify the H5FD_mirror_fapl_t struct */
+#define H5FD_MIRROR_FAPL_MAGIC 0xF8DD514C
 
-/* ============================================================================
- * Mirror VFD use and operation.
- * ============================================================================
+/**
+ * The version number of the H5FD_mirror_fapl_t configuration
+ * structure for the #H5FD_MIRROR driver
  */
+#define H5FD_MIRROR_CURR_FAPL_T_VERSION 1
 
-/* ---------------------------------------------------------------------------
- * Structure:   H5FD_mirror_fapl_t
+/** Max size of the remote_ip array in H5FD_mirror_fapl_t */
+#define H5FD_MIRROR_MAX_IP_LEN 32
+
+/**
+ *\struct H5FD_mirror_fapl_t
+ * \brief Configuration structure for H5Pset_fapl_mirror() / H5Pget_fapl_mirror()
  *
- * Used to pass configuration information to the Mirror VFD.
- * Populate components as appropriate and pass structure pointer to
- * `H5Pset_fapl_mirror()`.
+ * \details H5FD_mirror_fapl_t is a public structure that is used to pass
+ *          configuration data to the #H5FD_MIRROR driver via a File Access
+ *          Property List. A pointer to an instance of this structure is
+ *          a parameter to H5Pset_fapl_mirror() and H5Pget_fapl_mirror().
  *
- * `magic` (uint32_t)
+ * \var uint32_t H5FD_mirror_fapl_t::magic
  *      Semi-unique number to sanity-check pointers to this structure type.
- *      MUST equal H5FD_MIRROR_FAPL_MAGIC to be considered valid.
+ *      Must equal H5FD_MIRROR_FAPL_MAGIC to be considered valid.
  *
- * `version` (uint32_t)
- *      Indicates expected components of the structure.
+ * \var uint32_t H5FD_mirror_fapl_t::version
+ *      Version number of the H5FD_mirror_fapl_t structure. Any instance passed
+ *      to H5Pset_fapl_mirror() / H5Pget_fapl_mirror() must have a recognized version
+ *      number or an error will be raised. Currently, this field should be set
+ *      to #H5FD_MIRROR_CURR_FAPL_T_VERSION.
  *
- * `handshake_port (int)
- *      Port number to expect to reach the "Mirror Server" on the remote host.
+ * \var int H5FD_mirror_fapl_t::handshake_port
+ *      Port number on the remote host.
  *
- * `remote_ip` (char[])
- *      IP address string of "Mirror Server" remote host.
- * ---------------------------------------------------------------------------
+ * \var char H5FD_mirror_fapl_t::remote_ip[H5FD_MIRROR_MAX_IP_LEN + 1]
+ *      IP address string of the remote host.
  */
-#define H5FD_MIRROR_FAPL_MAGIC          0xF8DD514C
-#define H5FD_MIRROR_CURR_FAPL_T_VERSION 1
-#define H5FD_MIRROR_MAX_IP_LEN          32
 typedef struct H5FD_mirror_fapl_t {
     uint32_t magic;
     uint32_t version;
@@ -65,6 +69,10 @@ typedef struct H5FD_mirror_fapl_t {
     char     remote_ip[H5FD_MIRROR_MAX_IP_LEN + 1];
 } H5FD_mirror_fapl_t;
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /** @private
  *
  * \brief Private initializer for the mirror VFD
@@ -74,14 +82,33 @@ H5_DLL hid_t H5FD_mirror_init(void);
 /**
  * \ingroup FAPL
  *
- * \todo Add missing documentation
+ * \brief Queries a File Access Property List for #H5FD_MIRROR file driver properties
+ *
+ * \fapl_id
+ * \param[out] fa_out Pointer to #H5FD_MIRROR driver configuration structure
+ * \returns \herr_t
+ *
+ * \details H5Pget_fapl_mirror() queries the #H5FD_MIRROR driver properties as set
+ *          by H5Pset_fapl_mirror().
+ *
+ * \since 1.10.7
  */
 H5_DLL herr_t H5Pget_fapl_mirror(hid_t fapl_id, H5FD_mirror_fapl_t *fa_out);
 
 /**
  * \ingroup FAPL
  *
- * \todo Add missing documentation
+ * \brief Modifies the file access property list to use the #H5FD_MIRROR driver
+ *
+ * \fapl_id
+ * \param[in] fa Pointer to #H5FD_MIRROR driver configuration structure
+ *
+ * \returns \herr_t
+ *
+ * \details H5Pset_fapl_mirror() modifies the file access property list to use the
+ *          #H5FD_MIRROR driver.
+ *
+ * \since 1.10.7
  */
 H5_DLL herr_t H5Pset_fapl_mirror(hid_t fapl_id, H5FD_mirror_fapl_t *fa);