From 28e31fcbafc70ad6278ddc4f5656f92836cf4a7f Mon Sep 17 00:00:00 2001 From: bmribler <39579120+bmribler@users.noreply.github.com> Date: Wed, 27 Mar 2024 21:14:23 -0400 Subject: [PATCH] Add documentation (H5M) (#4259) --- src/H5Mpublic.h | 158 +++++++++++++++++++++++++----------------------- 1 file changed, 83 insertions(+), 75 deletions(-) diff --git a/src/H5Mpublic.h b/src/H5Mpublic.h index 48625a55382..e108a5c25d7 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 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 */ +#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 */ - /* Parameters for each operation */ + /** 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) */ - 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 */ + /* 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 */ - 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;