From bcb5e21163c980d40817db46c7e75580369e2499 Mon Sep 17 00:00:00 2001 From: Binh-Minh Date: Wed, 27 Mar 2024 11:14:33 -0400 Subject: [PATCH 1/4] Add documentation --- src/H5Mpublic.h | 154 +++++++++++++++++++++++++----------------------- 1 file changed, 81 insertions(+), 73 deletions(-) diff --git a/src/H5Mpublic.h b/src/H5Mpublic.h index 48625a55382..ba1c3cb990f 100644 --- a/src/H5Mpublic.h +++ b/src/H5Mpublic.h @@ -32,33 +32,37 @@ /* Macros defining operation IDs for map VOL callbacks (implemented using the * "optional" VOL callback) */ -#define H5VL_MAP_CREATE 1 -#define H5VL_MAP_OPEN 2 -#define H5VL_MAP_GET_VAL 3 -#define H5VL_MAP_EXISTS 4 -#define H5VL_MAP_PUT 5 -#define H5VL_MAP_GET 6 -#define H5VL_MAP_SPECIFIC 7 -#define H5VL_MAP_OPTIONAL 8 -#define H5VL_MAP_CLOSE 9 +#define H5VL_MAP_CREATE 1 /**< Callback operation ID for map create */ +#define H5VL_MAP_OPEN 2 /**< Callback operation ID for map open */ +#define H5VL_MAP_GET_VAL 3 /**< Callback operation ID for getting an associated value from a map */ +#define H5VL_MAP_EXISTS 4 /**< Callback operation ID for checking a map existence */ +#define H5VL_MAP_PUT 5 /**< Callback operation ID for putting a key-value pair to a map */ +#define H5VL_MAP_GET 6 /**< Callback operation ID for map get callback */ +#define H5VL_MAP_SPECIFIC 7 /**< Callback operation ID for map specific operation */ +#define H5VL_MAP_OPTIONAL 8 /**< Currently unused */ +#define H5VL_MAP_CLOSE 9 /**< Callback operation ID for terminating access to a map */ /*******************/ /* Public Typedefs */ /*******************/ -/* types for map GET callback */ +/** + * Types for map GET callback + */ typedef enum H5VL_map_get_t { - H5VL_MAP_GET_MAPL, /* map access property list */ - H5VL_MAP_GET_MCPL, /* map creation property list */ - H5VL_MAP_GET_KEY_TYPE, /* key type */ - H5VL_MAP_GET_VAL_TYPE, /* value type */ - H5VL_MAP_GET_COUNT /* key count */ + H5VL_MAP_GET_MAPL, /**< Callback operation ID for getting map access property list */ + H5VL_MAP_GET_MCPL, /**< Callback operation ID for getting map creation property list */ + H5VL_MAP_GET_KEY_TYPE, /**< Callback operation ID for getting the key datatype for a map */ + H5VL_MAP_GET_VAL_TYPE, /**< Callback operation ID for getting the value datatype for a map */ + H5VL_MAP_GET_COUNT /**< Callback operation ID for getting the number of key-value pairs stored in a map */ } H5VL_map_get_t; -/* types for map SPECIFIC callback */ +/** + * Types for map SPECIFIC callback + */ typedef enum H5VL_map_specific_t { - H5VL_MAP_ITER, /* H5Miterate */ - H5VL_MAP_DELETE /* H5Mdelete */ + H5VL_MAP_ITER, /**< Callback operation ID for iterating over all key-value pairs stored in the map */ + H5VL_MAP_DELETE /**< Callback operation ID for deleting a key-value pair stored in the map */ } H5VL_map_specific_t; //! @@ -68,112 +72,116 @@ typedef enum H5VL_map_specific_t { typedef herr_t (*H5M_iterate_t)(hid_t map_id, const void *key, void *op_data); //! -/* Parameters for map operations */ +/** + * Parameters for map operations + */ typedef union H5VL_map_args_t { - /* H5VL_MAP_CREATE */ + + /** H5VL_MAP_CREATE */ struct { - H5VL_loc_params_t loc_params; /* Location parameters for object */ - const char *name; /* Name of new map object */ - hid_t lcpl_id; /* Link creation property list for map */ - hid_t key_type_id; /* Datatype for map keys */ - hid_t val_type_id; /* Datatype for map values */ - hid_t mcpl_id; /* Map creation property list */ - hid_t mapl_id; /* Map access property list */ - void *map; /* Pointer to newly created map object (OUT) */ + H5VL_loc_params_t loc_params; /**< Location parameters for object */ + const char *name; /**< Name of new map object */ + hid_t lcpl_id; /**< Link creation property list for map */ + hid_t key_type_id; /**< Datatype for map keys */ + hid_t val_type_id; /**< Datatype for map values */ + hid_t mcpl_id; /**< Map creation property list */ + hid_t mapl_id; /**< Map access property list */ + void *map; /**< Pointer to newly created map object (OUT) */ } create; - /* H5VL_MAP_OPEN */ + /** H5VL_MAP_OPEN */ struct { - H5VL_loc_params_t loc_params; /* Location parameters for object */ - const char *name; /* Name of new map object */ - hid_t mapl_id; /* Map access property list */ - void *map; /* Pointer to newly created map object (OUT) */ + H5VL_loc_params_t loc_params; /**< Location parameters for object */ + const char *name; /**< Name of new map object */ + hid_t mapl_id; /**< Map access property list */ + void *map; /**< Pointer to newly created map object (OUT) */ } open; - /* H5VL_MAP_GET_VAL */ + /** H5VL_MAP_GET_VAL */ struct { - hid_t key_mem_type_id; /* Memory datatype for key */ - const void *key; /* Pointer to key */ - hid_t value_mem_type_id; /* Memory datatype for value */ - void *value; /* Buffer for value (OUT) */ + hid_t key_mem_type_id; /**< Memory datatype for key */ + const void *key; /**< Pointer to key */ + hid_t value_mem_type_id; /**< Memory datatype for value */ + void *value; /**< Buffer for value (OUT) */ } get_val; - /* H5VL_MAP_EXISTS */ + /** H5VL_MAP_EXISTS */ struct { - hid_t key_mem_type_id; /* Memory datatype for key */ - const void *key; /* Pointer to key */ - hbool_t exists; /* Flag indicating whether key exists in map (OUT) */ + hid_t key_mem_type_id; /**< Memory datatype for key */ + const void *key; /**< Pointer to key */ + hbool_t exists; /**< Flag indicating whether key exists in map (OUT) */ } exists; - /* H5VL_MAP_PUT */ + /** H5VL_MAP_PUT */ struct { - hid_t key_mem_type_id; /* Memory datatype for key */ - const void *key; /* Pointer to key */ - hid_t value_mem_type_id; /* Memory datatype for value */ - const void *value; /* Pointer to value */ + hid_t key_mem_type_id; /**< Memory datatype for key */ + const void *key; /**< Pointer to key */ + hid_t value_mem_type_id; /**< Memory datatype for value */ + const void *value; /**< Pointer to value */ } put; - /* H5VL_MAP_GET */ + /** H5VL_MAP_GET */ struct { - H5VL_map_get_t get_type; /* 'get' operation to perform */ + H5VL_map_get_t get_type; /**< 'get' operation to perform */ - /* Parameters for each operation */ + /** Parameters for each operation */ union { - /* H5VL_MAP_GET_MAPL */ + /** H5VL_MAP_GET_MAPL */ struct { - hid_t mapl_id; /* Map access property list ID (OUT) */ + hid_t mapl_id; /**< Get map access property list ID (OUT) */ } get_mapl; - /* H5VL_MAP_GET_MCPL */ + /** H5VL_MAP_GET_MCPL */ struct { - hid_t mcpl_id; /* Map creation property list ID (OUT) */ + hid_t mcpl_id; /**< Get map creation property list ID (OUT) */ } get_mcpl; - /* H5VL_MAP_GET_KEY_TYPE */ + /** H5VL_MAP_GET_KEY_TYPE */ struct { - hid_t type_id; /* Datatype ID for map's keys (OUT) */ + hid_t type_id; /**< Get datatype ID for map's keys (OUT) */ } get_key_type; - /* H5VL_MAP_GET_VAL_TYPE */ + /** H5VL_MAP_GET_VAL_TYPE */ struct { - hid_t type_id; /* Datatype ID for map's values (OUT) */ + hid_t type_id; /**< Get datatype ID for map's values (OUT) */ } get_val_type; - /* H5VL_MAP_GET_COUNT */ + /** H5VL_MAP_GET_COUNT */ struct { - hsize_t count; /* # of KV pairs in map (OUT) */ + hsize_t count; /**< Get number of key-value pairs in the map (OUT) */ } get_count; } args; } get; - /* H5VL_MAP_SPECIFIC */ + /** H5VL_MAP_SPECIFIC */ struct { - H5VL_map_specific_t specific_type; /* 'specific' operation to perform */ + H5VL_map_specific_t specific_type; + /**< 'specific' operation to perform, which are 'iterate' and 'del' currently */ - /* Parameters for each operation */ + /** Parameters for each operation */ union { /* H5VL_MAP_ITER */ struct { - H5VL_loc_params_t loc_params; /* Location parameters for object */ - hsize_t idx; /* Start/end iteration index (IN/OUT) */ - hid_t key_mem_type_id; /* Memory datatype for key */ - H5M_iterate_t op; /* Iteration callback routine */ - void *op_data; /* Pointer to callback context */ + H5VL_loc_params_t loc_params; /**< Location parameters for object */ + hsize_t idx; /**< Start/end iteration index (IN/OUT) */ + hid_t key_mem_type_id; /**< Memory datatype for key */ + H5M_iterate_t op; /**< Iteration callback routine */ + void *op_data; /**< Pointer to callback context */ } iterate; /* H5VL_MAP_DELETE */ struct { - H5VL_loc_params_t loc_params; /* Location parameters for object */ - hid_t key_mem_type_id; /* Memory datatype for key */ - const void *key; /* Pointer to key */ + H5VL_loc_params_t loc_params; /**< Location parameters for object */ + hid_t key_mem_type_id; /**< Memory datatype for key */ + const void *key; /**< Pointer to key */ } del; } args; } specific; - /* H5VL_MAP_OPTIONAL */ + /** H5VL_MAP_OPTIONAL */ /* Unused */ - /* H5VL_MAP_CLOSE */ + /** H5VL_MAP_CLOSE */ /* No args */ } H5VL_map_args_t; From 8ed5aa6bfa771b5154e7c4e33d53ff6708c284bb Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 27 Mar 2024 15:17:06 +0000 Subject: [PATCH 2/4] Committing clang-format changes --- src/H5Mpublic.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/H5Mpublic.h b/src/H5Mpublic.h index ba1c3cb990f..96617febce5 100644 --- a/src/H5Mpublic.h +++ b/src/H5Mpublic.h @@ -54,15 +54,15 @@ typedef enum H5VL_map_get_t { H5VL_MAP_GET_MCPL, /**< Callback operation ID for getting map creation property list */ H5VL_MAP_GET_KEY_TYPE, /**< Callback operation ID for getting the key datatype for a map */ H5VL_MAP_GET_VAL_TYPE, /**< Callback operation ID for getting the value datatype for a map */ - H5VL_MAP_GET_COUNT /**< Callback operation ID for getting the number of key-value pairs stored in a map */ + H5VL_MAP_GET_COUNT /**< Callback operation ID for getting the number of key-value pairs stored in a map */ } H5VL_map_get_t; /** * Types for map SPECIFIC callback */ typedef enum H5VL_map_specific_t { - H5VL_MAP_ITER, /**< Callback operation ID for iterating over all key-value pairs stored in the map */ - H5VL_MAP_DELETE /**< Callback operation ID for deleting a key-value pair stored in the map */ + H5VL_MAP_ITER, /**< Callback operation ID for iterating over all key-value pairs stored in the map */ + H5VL_MAP_DELETE /**< Callback operation ID for deleting a key-value pair stored in the map */ } H5VL_map_specific_t; //! @@ -156,7 +156,7 @@ typedef union H5VL_map_args_t { /** H5VL_MAP_SPECIFIC */ struct { H5VL_map_specific_t specific_type; - /**< 'specific' operation to perform, which are 'iterate' and 'del' currently */ + /**< 'specific' operation to perform, which are 'iterate' and 'del' currently */ /** Parameters for each operation */ union { From 9424e3f455fcddc315d00a5a675b35de8e510da0 Mon Sep 17 00:00:00 2001 From: Binh-Minh Date: Wed, 27 Mar 2024 17:47:18 -0400 Subject: [PATCH 3/4] Remove the mentioning of specific operations in a common place. --- src/H5Mpublic.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/H5Mpublic.h b/src/H5Mpublic.h index 96617febce5..2931e2bf1eb 100644 --- a/src/H5Mpublic.h +++ b/src/H5Mpublic.h @@ -156,11 +156,11 @@ typedef union H5VL_map_args_t { /** H5VL_MAP_SPECIFIC */ struct { H5VL_map_specific_t specific_type; - /**< 'specific' operation to perform, which are 'iterate' and 'del' currently */ + /**< 'specific' operation to perform */ /** Parameters for each operation */ union { - /* H5VL_MAP_ITER */ + /* H5VL_MAP_ITER specific operation */ struct { H5VL_loc_params_t loc_params; /**< Location parameters for object */ hsize_t idx; /**< Start/end iteration index (IN/OUT) */ @@ -169,7 +169,7 @@ typedef union H5VL_map_args_t { void *op_data; /**< Pointer to callback context */ } iterate; - /* H5VL_MAP_DELETE */ + /* H5VL_MAP_DELETE specific operation */ struct { H5VL_loc_params_t loc_params; /**< Location parameters for object */ hid_t key_mem_type_id; /**< Memory datatype for key */ From 74eafcef1f0c99b6f2916065d4672fa7625d568c Mon Sep 17 00:00:00 2001 From: Binh-Minh Date: Wed, 27 Mar 2024 17:50:52 -0400 Subject: [PATCH 4/4] Fix incorrect statement --- src/H5Mpublic.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/H5Mpublic.h b/src/H5Mpublic.h index 2931e2bf1eb..e108a5c25d7 100644 --- a/src/H5Mpublic.h +++ b/src/H5Mpublic.h @@ -35,7 +35,7 @@ #define H5VL_MAP_CREATE 1 /**< Callback operation ID for map create */ #define H5VL_MAP_OPEN 2 /**< Callback operation ID for map open */ #define H5VL_MAP_GET_VAL 3 /**< Callback operation ID for getting an associated value from a map */ -#define H5VL_MAP_EXISTS 4 /**< Callback operation ID for checking a map existence */ +#define H5VL_MAP_EXISTS 4 /**< Callback operation ID for checking if a value exists in a map */ #define H5VL_MAP_PUT 5 /**< Callback operation ID for putting a key-value pair to a map */ #define H5VL_MAP_GET 6 /**< Callback operation ID for map get callback */ #define H5VL_MAP_SPECIFIC 7 /**< Callback operation ID for map specific operation */