From ce1e43b038ed3d8aa00feeb0c4f9f3c05361a2c3 Mon Sep 17 00:00:00 2001
From: Michal Zientkiewicz <michalz@nvidia.com>
Date: Mon, 16 Jan 2023 10:41:09 +0100
Subject: [PATCH] Improve documentation.

Signed-off-by: Michal Zientkiewicz <michalz@nvidia.com>
---
 include/dali/c_api.h                     | 26 +++++++++++++--------
 include/dali/core/mm/default_resources.h | 29 +++++++++++++++++-------
 2 files changed, 37 insertions(+), 18 deletions(-)

diff --git a/include/dali/c_api.h b/include/dali/c_api.h
index 45ec773f0ac..2629af87ee2 100644
--- a/include/dali/c_api.h
+++ b/include/dali/c_api.h
@@ -584,27 +584,33 @@ DLL_PUBLIC void daliReleaseUnusedMemory();
 /**
  * @brief Preallocates device memory
  *
+ * The function ensures that after the call, the amount of memory given in `bytes` can be
+ * allocated from the pool (without further requests to the OS).
+ *
+ * The function works by allocating and then freeing the requested number of bytes.
+ * Any outstanding allocations are not taken into account - that is, the peak amount
+ * of memory allocated will be the sum of pre-existing allocation and the amount given
+ * in `bytes`.
+ *
  * @param device_id The ordinal number of the device to allocate the memory on. If negative,
  *                  the current device as indicated by cudaGetDevice is used.
  *
  * @return Zero, if the allocation was successful, otherwise nonzero
- *
- * @note The function works by allocating and then freeing the requested number of bytes.
- *       Any outstanding allocations are not taken into account - that is, the peak amount
- *       of memory allocated will be the sum of pre-existing allocation and the amount given
- *       in `bytes`.
  */
 DLL_PUBLIC int daliPreallocateDeviceMemory(size_t bytes, int device_id);
 
 /**
  * @brief Preallocates host pinned memory
  *
- * @return Zero, if the allocation was successful, otherwise nonzero
+ * The function ensures that after the call, the amount of memory given in `bytes` can be
+ * allocated from the pool (without further requests to the OS).
+ *
+ * The function works by allocating and then freeing the requested number of bytes.
+ * Any outstanding allocations are not taken into account - that is, the peak amount
+ * of memory allocated will be the sum of pre-existing allocation and the amount given
+ * in `bytes`.
  *
- * @note The function works by allocating and then freeing the requested number of bytes.
- *       Any outstanding allocations are not taken into account - that is, the peak amount
- *       of memory allocated will be the sum of pre-existing allocation and the amount given
- *       in `bytes`.
+ * @return Zero, if the allocation was successful, otherwise nonzero
  */
 DLL_PUBLIC int daliPreallocatePinnedMemory(size_t bytes);
 
diff --git a/include/dali/core/mm/default_resources.h b/include/dali/core/mm/default_resources.h
index d3c7f971163..081a9ffeaae 100644
--- a/include/dali/core/mm/default_resources.h
+++ b/include/dali/core/mm/default_resources.h
@@ -117,6 +117,9 @@ void SetDefaultDeviceResource(int device_id, std::shared_ptr<device_async_resour
  *
  * The memory pools hold memory for future use. This function will attempt to free that memory.
  * Note that memory blocks that are partially used cannot be released.
+ *
+ * @note If the relevant memory resource doesn't expose pool-like interface or none if its
+ *       accessible upstream resources exposes such an interface, then this function is a no-op.
  */
 DLL_PUBLIC
 void ReleaseUnusedMemory();
@@ -124,10 +127,15 @@ void ReleaseUnusedMemory();
 /**
  * @brief Preallocates device memory
  *
- * @note The function works by allocating and then freeing the requested number of bytes.
- *       Any outstanding allocations are not taken into account - that is, the peak amount
- *       of memory allocated will be the sum of pre-existing allocation and the amount given
- *       in `bytes`.
+ * The function ensures that after the call, the amount of memory given in `bytes` can be
+ * allocated from the pool (without further requests to the OS).
+ *
+ * The function works by allocating and then freeing the requested number of bytes.
+ * Any outstanding allocations are not taken into account - that is, the peak amount
+ * of memory allocated will be the sum of pre-existing allocation and the amount given
+ * in `bytes`.
+ *
+ * @throws std::bad_alloc
  */
 DLL_PUBLIC
 void PreallocateDeviceMemory(size_t bytes, int device_id = -1);
@@ -135,10 +143,15 @@ void PreallocateDeviceMemory(size_t bytes, int device_id = -1);
 /**
  * @brief Preallocates host pinned memory
  *
- * @note The function works by allocating and then freeing the requested number of bytes.
- *       Any outstanding allocations are not taken into account - that is, the peak amount
- *       of memory allocated will be the sum of pre-existing allocation and the amount given
- *       in `bytes`.
+ * The function ensures that after the call, the amount of memory given in `bytes` can be allocated
+ * from the pool (without further requests to the OS).
+ *
+ * The function works by allocating and then freeing the requested number of bytes.
+ * Any outstanding allocations are not taken into account - that is, the peak amount
+ * of memory allocated will be the sum of pre-existing allocation and the amount given
+ * in `bytes`.
+ *
+ * @throws std::bad_alloc
  */
 DLL_PUBLIC
 void PreallocatePinnedMemory(size_t bytes);