From ca217e2c71fd2a260eaa75227b00a754facd73ec Mon Sep 17 00:00:00 2001
From: mattjala <124107509+mattjala@users.noreply.github.com>
Date: Tue, 17 Sep 2024 11:06:03 -0500
Subject: [PATCH] Document usage for H5TSmutex_release/acquire() (#4836)

---
 src/H5TS.c | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/src/H5TS.c b/src/H5TS.c
index 590e20b70f..05d700c465 100644
--- a/src/H5TS.c
+++ b/src/H5TS.c
@@ -67,10 +67,12 @@ H5TS_api_info_t H5TS_api_info_p;
 /*--------------------------------------------------------------------------
  * Function:    H5TSmutex_acquire
  *
- * Purpose:     Attempts to acquire the HDF5 library global lock
+ * Purpose:     Attempts to acquire the HDF5 library global lock. Should be preceded by a call to
+ *              H5TSmutex_release().
  *
- * Note:        On success, the 'acquired' flag indicates if the HDF5 library
- *              global lock was acquired.
+ * Parameters:
+ *              lock_count; IN: The lock count that was held on the mutex before its release
+ *              acquired; OUT: Whether the HDF5 library global lock was acquired
  *
  * Return:      Non-negative on success / Negative on failure
  *
@@ -118,10 +120,17 @@ H5TSmutex_get_attempt_count(unsigned *count)
 /*--------------------------------------------------------------------------
  * Function:    H5TSmutex_release
  *
- * Purpose:     Releases the HDF5 library global lock
+ * Purpose:     Releases the HDF5 library global lock. Should be followed by a call to H5TSmutex_acquire().
+ *
+ *              This should be used by applications to temporarily release the lock in order to either perform
+ *              multi-threaded work of their own or yield control to another thread using HDF5. The value
+ *              returned in lock_count should be provided to H5TSmutex_acquire() in order to resume a
+ *              consistent library state.
+ *
+ * Parameters:
+ *              lock_count; OUT: The current lock count for the calling thread.
  *
  * Return:      Non-negative on success / Negative on failure
- *
  *--------------------------------------------------------------------------
  */
 herr_t