Add missing docs

Author: callumfare

offload/liboffload/API/Device.td

@@ -36,7 +36,7 @@ def : Enum {
 
 def : FptrTypedef {
   let name = "ol_device_iterate_cb_t";
-  let desc = "User-provided function called for each available device.";
+  let desc = "User-provided function to be used with `olIterateDevices`";
   let params = [
     Param<"ol_device_handle_t", "Device", "the device handle of the current iteration", PARAM_IN>,
     Param<"void*", "UserData", "optional user data", PARAM_IN_OPTIONAL>
@@ -46,12 +46,17 @@ def : FptrTypedef {
 
 def : Function {
   let name = "olIterateDevices";
-  let desc = "";
+  let desc = "Iterates over all available devices, calling the callback for each device.";
+  let details = [
+    "If the user-provided callback returns `false`, the iteration is stopped."
+  ];
   let params = [
     Param<"ol_device_iterate_cb_t", "Callback", "User-provided function called for each available device", PARAM_IN>,
     Param<"void*", "UserData", "Optional user data to pass to the callback", PARAM_IN_OPTIONAL>
   ];
-  let returns = [];
+  let returns = [
+    Return<"OL_ERRC_INVALID_DEVICE">
+  ];
 }
 
 def : Function {

offload/liboffload/API/Memory.td

@@ -49,7 +49,7 @@ def : Function {
     let name = "olMemcpy";
     let desc = "Enqueue a memcpy operation.";
     let details = [
-        "For host pointers, use the device returned by olGetHostDevice",
+        "For host pointers, use the host device belonging to the OL_PLATFORM_BACKEND_HOST platform.",
         "If a queue is specified, at least one device must be a non-host device",
         "If a queue is not specified, the memcpy happens synchronously"
     ];

offload/liboffload/include/generated/OffloadAPI.h

@@ -333,22 +333,26 @@ typedef enum ol_device_info_t {
 } ol_device_info_t;
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief User-provided function called for each available device.
+/// @brief User-provided function to be used with `olIterateDevices`
 typedef bool (*ol_device_iterate_cb_t)(
     // the device handle of the current iteration
     ol_device_handle_t Device,
     // optional user data
     void *UserData);
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief
+/// @brief Iterates over all available devices, calling the callback for each
+/// device.
 ///
 /// @details
+///    - If the user-provided callback returns `false`, the iteration is
+///    stopped.
 ///
 /// @returns
 ///     - ::OL_RESULT_SUCCESS
 ///     - ::OL_ERRC_UNINITIALIZED
 ///     - ::OL_ERRC_DEVICE_LOST
+///     - ::OL_ERRC_INVALID_DEVICE
 ///     - ::OL_ERRC_INVALID_NULL_HANDLE
 ///     - ::OL_ERRC_INVALID_NULL_POINTER
 OL_APIEXPORT ol_result_t OL_APICALL olIterateDevices(

offload/liboffload/src/OffloadImpl.cpp

@@ -291,11 +291,6 @@ ol_impl_result_t olIterateDevices_impl(ol_device_iterate_cb_t Callback,
   return OL_SUCCESS;
 }
 
-ol_impl_result_t olGetHostDevice_impl(ol_device_handle_t *Device) {
-  *Device = HostDevice();
-  return OL_SUCCESS;
-}
-
 TargetAllocTy convertOlToPluginAllocTy(ol_alloc_type_t Type) {
   switch (Type) {
   case OL_ALLOC_TYPE_DEVICE:

offload/unittests/OffloadAPI/program/olDestroyProgram.cpp

@@ -1,4 +1,4 @@
-//===------- Offload API tests - olReleaseProgram -------------------------===//
+//===------- Offload API tests - olDestroyProgram -------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.