Adds RELEASE.txt notes and updates Doxygen (#2377) (#2379)

3 files changed, 42 insertions, 8 deletions

diff --git a/release_docs/RELEASE.txt b/release_docs/RELEASE.txt
index fe06301..472932c 100644
--- a/release_docs/RELEASE.txt
+++ b/release_docs/RELEASE.txt
@@ -89,6 +89,38 @@ New Features
 
     Library:
     --------
+    - Overhauled the Virtual Object Layer (VOL)
+
+      The virtual object layer (VOL) was added in HDF5 1.12.0 but the initial
+      implementation required API-breaking changes to better support optional
+      operations and pass-through VOL connectors. The original VOL API is
+      now considered deprecated and VOL users and connector authors should
+      target the 1.14 VOL API.
+
+      The specific changes are too extensive to document in a release note, so
+      VOL users and connector authors should consult the updated VOL connector
+      author's guide and the 1.12-1.14 VOL migration guide.
+
+      (DER - 2022/12/28)
+
+    - H5VLquery_optional() signature change
+
+      The last parameter of this API call has changed from a pointer to hbool_t
+      to a pointer to uint64_t. Due to the changes in how optional operations
+      are handled in the 1.14 VOL API, we cannot make the old API call work
+      with the new scheme, so there is no API compatibility macro for it.
+
+      (DER - 2022/12/28)
+
+    - H5I_free_t callback signature change
+
+      In order to support asynchronous operations and future IDs, the signature
+      of the H5I_free_t callback has been modified to take a second 'request'
+      parameter. Due to the nature of the internal library changes, no API
+      compatibility macro is available for this change.
+
+      (DER - 2022/12/28)
+
     - Fix for CVE-2019-8396
 
       Malformed HDF5 files may have truncated content which does not match
diff --git a/src/H5Ipublic.h b/src/H5Ipublic.h
index c0ad6be..d699c92 100644
--- a/src/H5Ipublic.h
+++ b/src/H5Ipublic.h
@@ -76,13 +76,15 @@ typedef int64_t hid_t;
 #define H5I_INVALID_HID (-1)
 
 /**
- * A function for freeing objects. This function will be called with an object
- * ID type number and a pointer to the object. The function should free the
- * object and return non-negative to indicate that the object
- * can be removed from the ID type. If the function returns negative
- * (failure) then the object will remain in the ID type.
+ * A function for freeing objects. This function will be called with a pointer
+ * to the object and a pointer to a pointer to the asynchronous request object.
+ * The function should free the object and return non-negative to indicate that
+ * the object can be removed from the ID type. If the function returns negative
+ * (failure) then the object will remain in the ID type. For asynchronous
+ * operations and handling the request parameter, see the HDF5 user guide and
+ * VOL connector author guide.
  */
-typedef herr_t (*H5I_free_t)(void *, void **);
+typedef herr_t (*H5I_free_t)(void *obj, void **request);
 
 /**
  * The type of a function to compare objects & keys
diff --git a/src/H5VLpublic.h b/src/H5VLpublic.h
index c0a0e68..09b31af 100644
--- a/src/H5VLpublic.h
+++ b/src/H5VLpublic.h
@@ -401,7 +401,7 @@ H5_DLL herr_t H5VLunregister_connector(hid_t connector_id);
  * \param[out] flags Operation flags
  * \return \herr_t
  *
- * \since 1.12.0
+ * \since 1.12.1
  */
 H5_DLL herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_type, uint64_t *flags);
 /**
@@ -413,7 +413,7 @@ H5_DLL herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_t
  * \param[out] is_native Boolean determining whether object is a native VOL connector object
  * \return \herr_t
  *
- * \since 1.14.0
+ * \since 1.12.2
  */
 H5_DLL herr_t H5VLobject_is_native(hid_t obj_id, hbool_t *is_native);