Adds Doxygen VOL flag markup (#2340) (#2342)

* Initial doxygen markup

* Committing clang-format changes

* Adds Doxygen comments to VOL flags

* Committing clang-format changes

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

1 files changed, 63 insertions, 55 deletions

diff --git a/src/H5VLpublic.h b/src/H5VLpublic.h
index c4bc5a7..2683e0a 100644
--- a/src/H5VLpublic.h
+++ b/src/H5VLpublic.h
@@ -60,64 +60,72 @@
  */
 #define H5_VOL_MAX 65535
 
-/* Capability flags for connector */
-#define H5VL_CAP_FLAG_NONE             0x0000000000000000 /* No special connector capabilities */
-#define H5VL_CAP_FLAG_THREADSAFE       0x0000000000000001 /* Connector is threadsafe */
-#define H5VL_CAP_FLAG_ASYNC            0x0000000000000002 /* Connector performs operations asynchronously*/
-#define H5VL_CAP_FLAG_NATIVE_FILES     0x0000000000000004 /* Connector produces native file format */
-#define H5VL_CAP_FLAG_ATTR_BASIC       0x0000000000000008
-#define H5VL_CAP_FLAG_ATTR_MORE        0x0000000000000010
-#define H5VL_CAP_FLAG_DATASET_BASIC    0x0000000000000020
-#define H5VL_CAP_FLAG_DATASET_MORE     0x0000000000000040
-#define H5VL_CAP_FLAG_FILE_BASIC       0x0000000000000080
-#define H5VL_CAP_FLAG_FILE_MORE        0x0000000000000100
-#define H5VL_CAP_FLAG_GROUP_BASIC      0x0000000000000200
-#define H5VL_CAP_FLAG_GROUP_MORE       0x0000000000000400
-#define H5VL_CAP_FLAG_LINK_BASIC       0x0000000000000800
-#define H5VL_CAP_FLAG_LINK_MORE        0x0000000000001000
-#define H5VL_CAP_FLAG_MAP_BASIC        0x0000000000002000
-#define H5VL_CAP_FLAG_MAP_MORE         0x0000000000004000
-#define H5VL_CAP_FLAG_OBJECT_BASIC     0x0000000000008000
-#define H5VL_CAP_FLAG_OBJECT_MORE      0x0000000000010000
-#define H5VL_CAP_FLAG_REF_BASIC        0x0000000000020000
-#define H5VL_CAP_FLAG_REF_MORE         0x0000000000040000
-#define H5VL_CAP_FLAG_OBJ_REF          0x0000000000080000
-#define H5VL_CAP_FLAG_REG_REF          0x0000000000100000
-#define H5VL_CAP_FLAG_ATTR_REF         0x0000000000200000
-#define H5VL_CAP_FLAG_STORED_DATATYPES 0x0000000000400000
-#define H5VL_CAP_FLAG_CREATION_ORDER   0x0000000000800000
-#define H5VL_CAP_FLAG_ITERATE          0x0000000001000000
-#define H5VL_CAP_FLAG_STORAGE_SIZE     0x0000000002000000
-#define H5VL_CAP_FLAG_BY_IDX           0x0000000004000000
-#define H5VL_CAP_FLAG_GET_PLIST        0x0000000008000000
-#define H5VL_CAP_FLAG_FLUSH_REFRESH    0x0000000010000000
-#define H5VL_CAP_FLAG_EXTERNAL_LINKS   0x0000000020000000
-#define H5VL_CAP_FLAG_HARD_LINKS       0x0000000040000000
-#define H5VL_CAP_FLAG_SOFT_LINKS       0x0000000080000000
-#define H5VL_CAP_FLAG_UD_LINKS         0x0000000100000000
-#define H5VL_CAP_FLAG_TRACK_TIMES      0x0000000200000000
-#define H5VL_CAP_FLAG_MOUNT            0x0000000400000000
-#define H5VL_CAP_FLAG_FILTERS          0x0000000800000000
-#define H5VL_CAP_FLAG_FILL_VALUES      0x0000001000000000
+/*
+ * Capability flags for VOL connectors
+ */
+#define H5VL_CAP_FLAG_NONE          0x0000000000000000 /**< No special connector capabilities */
+#define H5VL_CAP_FLAG_THREADSAFE    0x0000000000000001 /**< Connector is threadsafe */
+#define H5VL_CAP_FLAG_ASYNC         0x0000000000000002 /**< Connector performs operations asynchronously*/
+#define H5VL_CAP_FLAG_NATIVE_FILES  0x0000000000000004 /**< Connector produces native file format */
+#define H5VL_CAP_FLAG_ATTR_BASIC    0x0000000000000008 /**< H5A create/delete/exists/open/close/read/write */
+#define H5VL_CAP_FLAG_ATTR_MORE     0x0000000000000010 /**< All other H5A API calls */
+#define H5VL_CAP_FLAG_DATASET_BASIC 0x0000000000000020 /**< H5D create/open/close/read/write */
+#define H5VL_CAP_FLAG_DATASET_MORE  0x0000000000000040 /**< All other H5D API calls */
+#define H5VL_CAP_FLAG_FILE_BASIC    0x0000000000000080 /**< H5F create/open/close/read/write */
+#define H5VL_CAP_FLAG_FILE_MORE     0x0000000000000100 /**< All other H5F API calls */
+#define H5VL_CAP_FLAG_GROUP_BASIC   0x0000000000000200 /**< H5G create/open/close */
+#define H5VL_CAP_FLAG_GROUP_MORE    0x0000000000000400 /**< All other H5G API calls*/
+#define H5VL_CAP_FLAG_LINK_BASIC    0x0000000000000800 /**< H5L exists/delete */
+#define H5VL_CAP_FLAG_LINK_MORE     0x0000000000001000 /**< All other H5L API calls */
+#define H5VL_CAP_FLAG_MAP_BASIC                                                                              \
+    0x0000000000002000 /**< H5M create/open/close/get*type/get_count/put/get/exists/delete */
+#define H5VL_CAP_FLAG_MAP_MORE         0x0000000000004000 /**< All other H5M API calls */
+#define H5VL_CAP_FLAG_OBJECT_BASIC     0x0000000000008000 /**< H5O open/close/exists */
+#define H5VL_CAP_FLAG_OBJECT_MORE      0x0000000000010000 /**< All other H5O API calls */
+#define H5VL_CAP_FLAG_REF_BASIC        0x0000000000020000 /**< H5Rdestroy */
+#define H5VL_CAP_FLAG_REF_MORE         0x0000000000040000 /**< All other H5R API calls */
+#define H5VL_CAP_FLAG_OBJ_REF          0x0000000000080000 /**< Connector supports object references */
+#define H5VL_CAP_FLAG_REG_REF          0x0000000000100000 /**< Connector supports regional references */
+#define H5VL_CAP_FLAG_ATTR_REF         0x0000000000200000 /**< Connector supports attribute references */
+#define H5VL_CAP_FLAG_STORED_DATATYPES 0x0000000000400000 /**< Connector supports stored datatypes */
+#define H5VL_CAP_FLAG_CREATION_ORDER   0x0000000000800000 /**< Connector tracks creation order */
+#define H5VL_CAP_FLAG_ITERATE          0x0000000001000000 /**< Connector supports iteration functions */
+#define H5VL_CAP_FLAG_STORAGE_SIZE     0x0000000002000000 /**< Connector can return a meaningful storage size */
+#define H5VL_CAP_FLAG_BY_IDX           0x0000000004000000 /**< "by index" API calls are supported */
+#define H5VL_CAP_FLAG_GET_PLIST                                                                              \
+    0x0000000008000000 /**< Connector can return the property lists used to create an object */
+#define H5VL_CAP_FLAG_FLUSH_REFRESH  0x0000000010000000 /**< flush/refresh calls are supported */
+#define H5VL_CAP_FLAG_EXTERNAL_LINKS 0x0000000020000000 /**< External links are supported */
+#define H5VL_CAP_FLAG_HARD_LINKS     0x0000000040000000 /**< Hard links are supported */
+#define H5VL_CAP_FLAG_SOFT_LINKS     0x0000000080000000 /**< Soft links are supported */
+#define H5VL_CAP_FLAG_UD_LINKS       0x0000000100000000 /**< User-defined links are supported */
+#define H5VL_CAP_FLAG_TRACK_TIMES    0x0000000200000000 /**< Connector tracks creation, etc. times */
+#define H5VL_CAP_FLAG_MOUNT          0x0000000400000000 /**< H5Fmount/unmount supported */
+#define H5VL_CAP_FLAG_FILTERS        0x0000000800000000 /**< Connector implements a filter pipeline */
+#define H5VL_CAP_FLAG_FILL_VALUES    0x0000001000000000 /**< Connector allows fill values to be set */
 
-/* Flags to return from H5VLquery_optional API and 'opt_query' callbacks */
-/* Note: Operations which access multiple objects' data or metadata in a
- *      container should be registered as file-level optional operations.
- *      (e.g. "H5Dwrite_multi" takes a list of datasets to write data to, so
- *      a VOL connector that implemented it should register it as an optional
- *      file operation, and pass-through VOL connectors that are stacked above
- *      the connector that registered it should assume that dataset elements
- *      for _any_ dataset in the file could be written to)
+/**
+ * \ingroup H5VLDEF
+ *
+ * Flags to return from H5VLquery_optional API and 'opt_query' callbacks
+ *
+ * \details Operations which access multiple objects' data or metadata in a
+ *          container should be registered as file-level optional operations.
+ *          (e.g. "H5Dwrite_multi" takes a list of datasets to write data to, so
+ *          a VOL connector that implemented it should register it as an optional
+ *          file operation, and pass-through VOL connectors that are stacked above
+ *          the connector that registered it should assume that dataset elements
+ *          for _any_ dataset in the file could be written to)
  */
-#define H5VL_OPT_QUERY_SUPPORTED       0x0001 /* VOL connector supports this operation */
-#define H5VL_OPT_QUERY_READ_DATA       0x0002 /* Operation reads data for object */
-#define H5VL_OPT_QUERY_WRITE_DATA      0x0004 /* Operation writes data for object */
-#define H5VL_OPT_QUERY_QUERY_METADATA  0x0008 /* Operation reads metadata for object */
-#define H5VL_OPT_QUERY_MODIFY_METADATA 0x0010 /* Operation modifies metadata for object */
+#define H5VL_OPT_QUERY_SUPPORTED       0x0001 /**< VOL connector supports this operation */
+#define H5VL_OPT_QUERY_READ_DATA       0x0002 /**< Operation reads data for object */
+#define H5VL_OPT_QUERY_WRITE_DATA      0x0004 /**< Operation writes data for object */
+#define H5VL_OPT_QUERY_QUERY_METADATA  0x0008 /**< Operation reads metadata for object */
+#define H5VL_OPT_QUERY_MODIFY_METADATA 0x0010 /**< Operation modifies metadata for object */
 #define H5VL_OPT_QUERY_COLLECTIVE                                                                            \
-    0x0020 /* Operation is collective (operations without this flag are assumed to be independent) */
-#define H5VL_OPT_QUERY_NO_ASYNC  0x0040 /* Operation may NOT be executed asynchronously */
-#define H5VL_OPT_QUERY_MULTI_OBJ 0x0080 /* Operation involves multiple objects */
+    0x0020 /**< Operation is collective (operations without this flag are assumed to be independent) */
+#define H5VL_OPT_QUERY_NO_ASYNC  0x0040 /**< Operation may NOT be executed asynchronously */
+#define H5VL_OPT_QUERY_MULTI_OBJ 0x0080 /**< Operation involves multiple objects */
 
 /*******************/
 /* Public Typedefs */