Added note about leaving callback functions properly. (#5127)

Added the alias \callback_note to APIs with a user callback function.  The note is
brief and refers to a more detail note in a central place, i.e., alias cpp_c_api_note.

Fixes issue GH-5089

doxygen/aliases

@@ -250,7 +250,8 @@ ALIASES += es_id{1}="\param[in] \1 Event set identifier"
 # Others
 ################################################################################
 
-ALIASES += cpp_c_api_note="\attention \Bold{C++ Developers using HDF5 C-API functions beware:}\n Several functions in this C-API take function pointers or callbacks as arguments. Examples include H5Pset_elink_cb(), H5Pset_type_conv_cb(), H5Tconvert(), and H5Ewalk2(). Application code must ensure that those callback functions return normally such to allow the HDF5 to manage its resources and maintain a consistent state. For instance, those functions must not use the C \c setjmp / \c longjmp mechanism to leave those callback functions. Within the context of C++, any exceptions thrown within the callback function must be caught, such as with a \TText{catch(…)} statement. Any exception state can be placed within the provided user data function call arguments, and may be thrown again once the calling function has returned. Exceptions raised and not handled inside the callback are not supported as it might leave the HDF5 library in an inconsistent state. Similarly, using C++20 coroutines cannot be used as callbacks, since they do not support plain return statements. If a callback function yields execution to another C++20 coroutine calling HDF5 functions as well, this may lead to undefined behavior."
+ALIASES += cpp_c_api_note="\anchor cpp_c_api_note \attention \Bold{C++ Developers using HDF5 C-API functions beware:}\n Several functions in this C-API take function pointers or callbacks as arguments. Examples include H5Pset_elink_cb(), H5Pset_type_conv_cb(), H5Tconvert(), and H5Ewalk2(). Application code must ensure that those callback functions return normally such to allow the HDF5 to manage its resources and maintain a consistent state. For instance, those functions must not use the C \c setjmp / \c longjmp mechanism to leave those callback functions. Within the context of C++, any exceptions thrown within the callback function must be caught, such as with a \TText{catch(…)} statement. Any exception state can be placed within the provided user data function call arguments, and may be thrown again once the calling function has returned. Exceptions raised and not handled inside the callback are not supported as it might leave the HDF5 library in an inconsistent state. Similarly, using C++20 coroutines cannot be used as callbacks, since they do not support plain return statements. If a callback function yields execution to another C++20 coroutine calling HDF5 functions as well, this may lead to undefined behavior."
+ALIASES += callback_note="\attention \Bold{Leaving callback functions:}\n The callback function must return normally, even in the case of error.  Returning with H5_ITER_ERROR, instead of leaving by means of exceptions, exit() function, etc... will allow the HDF5 library to manage its resources and maintain a consistent state. See \ref cpp_c_api_note \"C++ Developers using HDF5 C-API functions\" warning for detail."
 ALIASES += par_compr_note="\attention If you are planning to use compression with parallel HDF5, ensure that calls to H5Dwrite() occur in collective mode. In other words, all MPI ranks (in the relevant communicator) call H5Dwrite() and pass a dataset transfer property list with the MPI-IO collective option property set to #H5FD_MPIO_COLLECTIVE_IO.\n Note that data transformations are currently \Bold{not} supported when writing to datasets in parallel and with compression enabled."
 ALIASES += sa_metadata_ops="\sa \li H5Pget_all_coll_metadata_ops() \li H5Pget_coll_metadata_write() \li H5Pset_all_coll_metadata_ops() \li H5Pset_coll_metadata_write() \li \ref maybe_metadata_reads"
 

src/H5Apublic.h

@@ -52,6 +52,8 @@ typedef struct {
  *              indicating failure. The iterator can be restarted at the next
  *              attribute.
  *
+ * \callback_note
+ *
  * \since 1.8.0
  *
  */
@@ -661,6 +663,8 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id);
  * \warning   Adding or removing attributes to the object during iteration
  *            will lead to undefined behavior.
  *
+ * \callback_note
+ *
  * \since 1.8.0
  *
  */
@@ -1191,6 +1195,8 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id);
  * \warning   Adding or removing attributes to the object during iteration
  *            will lead to undefined behavior.
  *
+ * \callback_note
+ *
  * \version 1.8.0 The function \p H5Aiterate was renamed to H5Aiterate1()
  *                and deprecated in this release.
  * \since 1.0.0

src/H5Dpublic.h

@@ -243,6 +243,8 @@ typedef herr_t (*H5D_gather_func_t)(const void *dst_buf, size_t dst_buf_bytes_us
  *          \li A negative (#H5_ITER_ERROR) causes the iterator to immediately
  *              return that value, indicating failure.
  *
+ * \callback_note
+ *
  * \since 1.14.0
  *
  */
@@ -732,6 +734,8 @@ H5_DLL herr_t H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, u
  * Iterate over all chunked datasets and chunks in a file.
  * \snippet H5D_examples.c H5Ovisit_cb
  *
+ * \callback_note
+ *
  * \since 1.14.0
  *
  */
@@ -1320,6 +1324,8 @@ H5_DLL herr_t H5Dread_chunk(hid_t dset_id, hid_t dxpl_id, const hsize_t *offset,
  * \warning   Modifying the selection of \p space_id during iteration
  *            will lead to undefined behavior.
  *
+ * \callback_note
+ *
  * \since 1.10.2
  *
  */
@@ -1608,6 +1614,8 @@ H5_DLL herr_t H5Dscatter(H5D_scatter_func_t op, void *op_data, hid_t type_id, hi
  *          in \p dst_buf. The callback function should return zero (0)
  *          to indicate success, and a negative value to indicate failure.
  *
+ * \callback_note
+ *
  * \since 1.10.2
  *
  */

src/H5Gpublic.h

@@ -1032,6 +1032,8 @@ H5_DLL int H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize, char *
  * \warning  Adding or removing members to the group during iteration
  *           will lead to undefined behavior.
  *
+ * \callback_note
+ *
  * \version 1.8.0 Function deprecated in this release.
  *
  * \since 1.0.0

src/H5Ipublic.h

@@ -610,6 +610,8 @@ H5_DLL void *H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key);
  * \warning  Adding or removing members of the identifier type during iteration
  *           will lead to undefined behavior.
  *
+ * \callback_note
+ *
  * \since 1.12.0
  *
  */

src/H5Lpublic.h

@@ -914,6 +914,7 @@ H5_DLL ssize_t H5Lget_name_by_idx(hid_t loc_id, const char *group_name, H5_index
  *          This does not limit the ability to change link destinations
  *          while iterating, but caution is advised.
  *
+ * \callback_note
  *
  * \since 1.12.0
  *
@@ -999,6 +1000,8 @@ H5_DLL herr_t H5Literate_async(hid_t group_id, H5_index_t idx_type, H5_iter_orde
  * \note H5Literate_by_name2() is the same as H5Literate2(), except that
  *       H5Literate2() always proceeds in alphanumeric order.
  *
+ * \callback_note
+ *
  * \since 1.12.0
  *
  * \see H5Literate(), H5Lvisit()
@@ -1083,6 +1086,8 @@ H5_DLL herr_t H5Literate_by_name2(hid_t loc_id, const char *group_name, H5_index
  *          presented to the application for whatever processing the
  *          application requires.
  *
+ * \callback_note
+ *
  * \since 1.12.0
  *
  * \see H5Literate()
@@ -1168,6 +1173,8 @@ H5_DLL herr_t H5Lvisit2(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order
  *          file has been presented to the application for whatever processing
  *          the application requires.
  *
+ * \callback_note
+ *
  * \since 1.12.0
  *
  */
@@ -1680,6 +1687,8 @@ H5_DLL herr_t H5Lget_info_by_idx1(hid_t loc_id, const char *group_name, H5_index
  *          This does not limit the ability to change link destinations
  *          while iterating, but caution is advised.
  *
+ * \callback_note
+ *
  * \version 1.12.0 Function was deprecated in this release.
  * \since 1.8.0
  *
@@ -1749,6 +1758,8 @@ H5_DLL herr_t H5Literate1(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t ord
  *       recursion, explicitly calling H5Literate_by_name1() on discovered
  *       subgroups.
  *
+ * \callback_note
+ *
  * \note H5Literate_by_name1() is the same as H5Giterate(), except that
  *       H5Giterate() always proceeds in lexicographic order.
  *
@@ -1842,6 +1853,8 @@ H5_DLL herr_t H5Literate_by_name1(hid_t loc_id, const char *group_name, H5_index
  *          presented to the application for whatever processing the
  *          application requires.
  *
+ * \callback_note
+ *
  * \version 1.12.0 Function was renamed from H5Lvisit() to H5Lvisit1() and
  *                 deprecated.
  *
@@ -1935,6 +1948,8 @@ H5_DLL herr_t H5Lvisit1(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order
  *          file has been presented to the application for whatever processing
  *          the application requires.
  *
+ * \callback_note
+ *
  * \version 1.12.0 Function renamed from H5Lvisit_by_name() to
  *                 H5Lvisit_by_name1() and deprecated.
  *

src/H5Mpublic.h

@@ -571,6 +571,8 @@ H5_DLL herr_t H5Mexists(hid_t map_id, hid_t key_mem_type_id, const void *key, hb
  *  \warning Adding or removing key-value pairs to the map during iteration
  *           will lead to undefined behavior.
  *
+ * \callback_note
+ *
  * \since 1.12.0
  *
  */
@@ -615,6 +617,8 @@ H5_DLL herr_t H5Miterate(hid_t map_id, hsize_t *idx, hid_t key_mem_type_id, H5M_
  *  \warning Adding or removing key-value pairs to the map during iteration
  *           will lead to undefined behavior.
  *
+ * \callback_note
+ *
  * \since 1.12.0
  *
  */

src/H5Opublic.h

@@ -1208,6 +1208,8 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm
  *          group change during the iteration, the resulting behavior
  *          is undefined.
  *
+ * \callback_note
+ *
  * \par Example
  *      An example snippet from test/links.c:
  *      \snippet links.c H5Ovisit3_snip
@@ -1311,6 +1313,8 @@ H5_DLL herr_t H5Ovisit3(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
  *          in the file has been presented to the application for whatever
  *          processing the application requires.
  *
+ * \callback_note
+ *
  * \par Example
  *      An example snippet from test/links.c:
  *      \snippet links.c H5Ovisit_by_name3_snip
@@ -2254,6 +2258,8 @@ H5_DLL herr_t H5Ovisit1(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
  *          in the file has been presented to the application for whatever
  *          processing the application requires.
  *
+ * \callback_note
+ *
  * \version 1.10.5 The macro #H5Ovisit_by_name was removed and the function
  *          H5Ovisit_by_name1() was copied to #H5Ovisit_by_name.
  * \version 1.10.3 The H5Ovisit_by_name() function was renamed to H5Ovisit_by_name1(),
@@ -2346,6 +2352,7 @@ H5_DLL herr_t H5Ovisit_by_name1(hid_t loc_id, const char *obj_name, H5_index_t i
  *          group change during the iteration, the resulting behavior
  *          is undefined.
  *
+ * \callback_note
  *
  * \since 1.10.3
  *
@@ -2456,6 +2463,8 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
  *          in the file has been presented to the application for whatever
  *          processing the application requires.
  *
+ * \callback_note
+ *
  * \since 1.10.3
  *
  */

src/H5Ppublic.h

@@ -8235,6 +8235,8 @@ H5_DLL herr_t H5Pset_preserve(hid_t plist_id, hbool_t status);
  *          function prototype is as follows:
  *          \snippet H5Tpublic.h H5T_conv_except_func_t_snip
  *
+ * \callback_note
+ *
  * \since 1.8.0
  *
  */