[NFC] Manual reflow of some awkward comments

The comments are now more left-aligned leaving more space for prose.

Author: ldrumm

source/adapters/cuda/ur_interface_loader.cpp

@@ -268,10 +268,10 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetDeviceProcAddrTable(
 }
 
 UR_DLLEXPORT ur_result_t UR_APICALL urGetCommandBufferExpProcAddrTable(
-    ur_api_version_t version, ///< [in] API version requested
-    ur_command_buffer_exp_dditable_t
-        *pDdiTable ///< [in,out] pointer to table of DDI function pointers
-) {
+    /// [in] API version requested
+    ur_api_version_t version,
+    /// [in,out] pointer to table of DDI function pointers
+    ur_command_buffer_exp_dditable_t *pDdiTable) {
   auto retVal = validateProcInputs(version, pDdiTable);
   if (UR_RESULT_SUCCESS != retVal) {
     return retVal;
@@ -368,10 +368,10 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetUSMExpProcAddrTable(
 }
 
 UR_DLLEXPORT ur_result_t UR_APICALL urGetVirtualMemProcAddrTable(
-    ur_api_version_t version, ///< [in] API version requested
-    ur_virtual_mem_dditable_t
-        *pDdiTable ///< [in,out] pointer to table of DDI function pointers
-) {
+    /// [in] API version requested
+    ur_api_version_t version,
+    /// [in,out] pointer to table of DDI function pointers
+    ur_virtual_mem_dditable_t *pDdiTable) {
   auto retVal = validateProcInputs(version, pDdiTable);
   if (UR_RESULT_SUCCESS != retVal) {
     return retVal;
@@ -389,10 +389,10 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetVirtualMemProcAddrTable(
 }
 
 UR_DLLEXPORT ur_result_t UR_APICALL urGetPhysicalMemProcAddrTable(
-    ur_api_version_t version, ///< [in] API version requested
-    ur_physical_mem_dditable_t
-        *pDdiTable ///< [in,out] pointer to table of DDI function pointers
-) {
+    /// [in] API version requested
+    ur_api_version_t version,
+    /// [in,out] pointer to table of DDI function pointers
+    ur_physical_mem_dditable_t *pDdiTable) {
   auto retVal = validateProcInputs(version, pDdiTable);
   if (UR_RESULT_SUCCESS != retVal) {
     return retVal;

source/adapters/cuda/usm.cpp

@@ -439,12 +439,13 @@ bool ur_usm_pool_handle_t_::hasUMFPool(umf_memory_pool_t *umf_pool) {
 }
 
 UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolCreate(
-    ur_context_handle_t Context, ///< [in] handle of the context object
-    ur_usm_pool_desc_t
-        *PoolDesc, ///< [in] pointer to USM pool descriptor. Can be chained with
-                   ///< ::ur_usm_pool_limits_desc_t
-    ur_usm_pool_handle_t *Pool ///< [out] pointer to USM memory pool
-) {
+    /// [in] handle of the context object
+    ur_context_handle_t Context,
+    /// [in] pointer to USM pool descriptor. Can be chained with
+    /// ::ur_usm_pool_limits_desc_t
+    ur_usm_pool_desc_t *PoolDesc,
+    /// [out] pointer to USM memory pool
+    ur_usm_pool_handle_t *Pool) {
   // Without pool tracking we can't free pool allocations.
 #ifdef UMF_ENABLE_POOL_TRACKING
   if (PoolDesc->flags & UR_USM_POOL_FLAG_ZERO_INITIALIZE_BLOCK) {
@@ -470,15 +471,15 @@ UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolCreate(
 }
 
 UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolRetain(
-    ur_usm_pool_handle_t Pool ///< [in] pointer to USM memory pool
-) {
+    /// [in] pointer to USM memory pool
+    ur_usm_pool_handle_t Pool) {
   Pool->incrementReferenceCount();
   return UR_RESULT_SUCCESS;
 }
 
 UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolRelease(
-    ur_usm_pool_handle_t Pool ///< [in] pointer to USM memory pool
-) {
+    /// [in] pointer to USM memory pool
+    ur_usm_pool_handle_t Pool) {
   if (Pool->decrementReferenceCount() > 0) {
     return UR_RESULT_SUCCESS;
   }
@@ -488,14 +489,16 @@ UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolRelease(
 }
 
 UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolGetInfo(
-    ur_usm_pool_handle_t hPool,  ///< [in] handle of the USM memory pool
-    ur_usm_pool_info_t propName, ///< [in] name of the pool property to query
-    size_t propSize, ///< [in] size in bytes of the pool property value provided
-    void *pPropValue, ///< [out][optional][typename(propName, propSize)] value
-                      ///< of the pool property
-    size_t *pPropSizeRet ///< [out][optional] size in bytes returned in pool
-                         ///< property value
-) {
+    /// [in] handle of the USM memory pool
+    ur_usm_pool_handle_t hPool,
+    /// [in] name of the pool property to query
+    ur_usm_pool_info_t propName,
+    /// [in] size in bytes of the pool property value provided
+    size_t propSize,
+    /// [out][optional][typename(propName, propSize)] value of the pool property
+    void *pPropValue,
+    /// [out][optional] size in bytes returned in pool property value
+    size_t *pPropSizeRet) {
   UrReturnHelper ReturnValue(propSize, pPropValue, pPropSizeRet);
 
   switch (propName) {

source/adapters/hip/ur_interface_loader.cpp

@@ -335,10 +335,10 @@ urGetUSMExpProcAddrTable(ur_api_version_t, ur_usm_exp_dditable_t *) {
 }
 
 UR_DLLEXPORT ur_result_t UR_APICALL urGetVirtualMemProcAddrTable(
-    ur_api_version_t version, ///< [in] API version requested
-    ur_virtual_mem_dditable_t
-        *pDdiTable ///< [in,out] pointer to table of DDI function pointers
-) {
+    /// [in] API version requested
+    ur_api_version_t version,
+    /// [in,out] pointer to table of DDI function pointers
+    ur_virtual_mem_dditable_t *pDdiTable) {
   auto retVal = validateProcInputs(version, pDdiTable);
   if (UR_RESULT_SUCCESS != retVal) {
     return retVal;
@@ -356,10 +356,10 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetVirtualMemProcAddrTable(
 }
 
 UR_DLLEXPORT ur_result_t UR_APICALL urGetPhysicalMemProcAddrTable(
-    ur_api_version_t version, ///< [in] API version requested
-    ur_physical_mem_dditable_t
-        *pDdiTable ///< [in,out] pointer to table of DDI function pointers
-) {
+    /// [in] API version requested
+    ur_api_version_t version,
+    /// [in,out] pointer to table of DDI function pointers
+    ur_physical_mem_dditable_t *pDdiTable) {
   auto retVal = validateProcInputs(version, pDdiTable);
   if (UR_RESULT_SUCCESS != retVal) {
     return retVal;

source/adapters/hip/usm.cpp

@@ -382,12 +382,13 @@ bool ur_usm_pool_handle_t_::hasUMFPool(umf_memory_pool_t *umf_pool) {
 }
 
 UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolCreate(
-    ur_context_handle_t Context, ///< [in] handle of the context object
-    ur_usm_pool_desc_t
-        *PoolDesc, ///< [in] pointer to USM pool descriptor. Can be chained with
-                   ///< ::ur_usm_pool_limits_desc_t
-    ur_usm_pool_handle_t *Pool ///< [out] pointer to USM memory pool
-) {
+    /// [in] handle of the context object
+    ur_context_handle_t Context,
+    /// [in] pointer to USM pool descriptor. Can be chained with
+    /// ::ur_usm_pool_limits_desc_t
+    ur_usm_pool_desc_t *PoolDesc,
+    /// [out] pointer to USM memory pool
+    ur_usm_pool_handle_t *Pool) {
   // Without pool tracking we can't free pool allocations.
 #ifdef UMF_ENABLE_POOL_TRACKING
   if (PoolDesc->flags & UR_USM_POOL_FLAG_ZERO_INITIALIZE_BLOCK) {
@@ -413,15 +414,15 @@ UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolCreate(
 }
 
 UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolRetain(
-    ur_usm_pool_handle_t Pool ///< [in] pointer to USM memory pool
-) {
+    /// [in] pointer to USM memory pool
+    ur_usm_pool_handle_t Pool) {
   Pool->incrementReferenceCount();
   return UR_RESULT_SUCCESS;
 }
 
 UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolRelease(
-    ur_usm_pool_handle_t Pool ///< [in] pointer to USM memory pool
-) {
+    /// [in] pointer to USM memory pool
+    ur_usm_pool_handle_t Pool) {
   if (Pool->decrementReferenceCount() > 0) {
     return UR_RESULT_SUCCESS;
   }
@@ -431,14 +432,16 @@ UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolRelease(
 }
 
 UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolGetInfo(
-    ur_usm_pool_handle_t hPool,  ///< [in] handle of the USM memory pool
-    ur_usm_pool_info_t propName, ///< [in] name of the pool property to query
-    size_t propSize, ///< [in] size in bytes of the pool property value provided
-    void *pPropValue, ///< [out][optional][typename(propName, propSize)] value
-                      ///< of the pool property
-    size_t *pPropSizeRet ///< [out][optional] size in bytes returned in pool
-                         ///< property value
-) {
+    /// [in] handle of the USM memory pool
+    ur_usm_pool_handle_t hPool,
+    /// [in] name of the pool property to query
+    ur_usm_pool_info_t propName,
+    /// [in] size in bytes of the pool property value provided
+    size_t propSize,
+    /// [out][optional][typename(propName, propSize)] value of the pool property
+    void *pPropValue,
+    /// [out][optional] size in bytes returned in pool property value
+    size_t *pPropSizeRet) {
   UrReturnHelper ReturnValue(propSize, pPropValue, pPropSizeRet);
 
   switch (propName) {

source/adapters/level_zero/adapter.cpp

@@ -626,19 +626,16 @@ ur_result_t adapterStateTeardown() {
 
 namespace ur::level_zero {
 ur_result_t urAdapterGet(
-    uint32_t NumEntries, ///< [in] the number of platforms to be added to
-                         ///< phAdapters. If phAdapters is not NULL, then
-                         ///< NumEntries should be greater than zero, otherwise
-                         ///< ::UR_RESULT_ERROR_INVALID_SIZE, will be returned.
-    ur_adapter_handle_t
-        *Adapters, ///< [out][optional][range(0, NumEntries)] array of handle of
-                   ///< adapters. If NumEntries is less than the number of
-                   ///< adapters available, then
-                   ///< ::urAdapterGet shall only retrieve that number of
-                   ///< platforms.
-    uint32_t *NumAdapters ///< [out][optional] returns the total number of
-                          ///< adapters available.
-) {
+    /// [in] the number of platforms to be added to phAdapters. If phAdapters is
+    /// not NULL, then NumEntries should be greater than zero, otherwise
+    /// ::UR_RESULT_ERROR_INVALID_SIZE, will be returned.
+    uint32_t NumEntries,
+    /// [out][optional][range(0, NumEntries)] array of handle of adapters.
+    /// If NumEntries is less than the number of adapters available, then
+    /// ::urAdapterGet shall only retrieve that number of platforms.
+    ur_adapter_handle_t *Adapters,
+    /// [out][optional] returns the total number of adapters available.
+    uint32_t *NumAdapters) {
   if (NumEntries > 0 && Adapters) {
     if (GlobalAdapter) {
       std::lock_guard<std::mutex> Lock{GlobalAdapter->Mutex};
@@ -688,12 +685,14 @@ ur_result_t urAdapterRetain(ur_adapter_handle_t) {
 }
 
 ur_result_t urAdapterGetLastError(
-    ur_adapter_handle_t,  ///< [in] handle of the platform instance
-    const char **Message, ///< [out] pointer to a C string where the adapter
-                          ///< specific error message will be stored.
-    int32_t *Error ///< [out] pointer to an integer where the adapter specific
-                   ///< error code will be stored.
-) {
+    /// [in] handle of the platform instance
+    ur_adapter_handle_t,
+    /// [out] pointer to a C string where the adapter specific error message
+    /// will be stored.
+    const char **Message,
+    /// [out] pointer to an integer where the adapter specific error code will
+    /// be stored.
+    int32_t *Error) {
   *Message = ErrorMessage;
   *Error = ErrorAdapterNativeCode;
 

source/adapters/level_zero/context.cpp

@@ -21,14 +21,14 @@
 namespace ur::level_zero {
 
 ur_result_t urContextCreate(
-    uint32_t DeviceCount, ///< [in] the number of devices given in phDevices
-    const ur_device_handle_t
-        *Devices, ///< [in][range(0, DeviceCount)] array of handle of devices.
-    const ur_context_properties_t
-        *Properties, ///< [in][optional] pointer to context creation properties.
-    ur_context_handle_t
-        *RetContext ///< [out] pointer to handle of context object created
-) {
+    /// [in] the number of devices given in phDevices
+    uint32_t DeviceCount,
+    /// [in][range(0, DeviceCount)] array of handle of devices.
+    const ur_device_handle_t *Devices,
+    /// [in][optional] pointer to context creation properties.
+    const ur_context_properties_t *Properties,
+    /// [out] pointer to handle of context object created
+    ur_context_handle_t *RetContext) {
   std::ignore = Properties;
 
   ur_platform_handle_t Platform = Devices[0]->Platform;
@@ -58,16 +58,16 @@ ur_result_t urContextCreate(
 }
 
 ur_result_t urContextRetain(
-    ur_context_handle_t
-        Context ///< [in] handle of the context to get a reference of.
-) {
+
+    /// [in] handle of the context to get a reference of.
+    ur_context_handle_t Context) {
   Context->RefCount.increment();
   return UR_RESULT_SUCCESS;
 }
 
 ur_result_t urContextRelease(
-    ur_context_handle_t Context ///< [in] handle of the context to release.
-) {
+    /// [in] handle of the context to release.
+    ur_context_handle_t Context) {
   ur_platform_handle_t Plt = Context->getPlatform();
   std::unique_lock<ur_shared_mutex> ContextsLock(Plt->ContextsMutex,
                                                  std::defer_lock);
@@ -90,18 +90,20 @@ static const bool UseMemcpy2DOperations = [] {
 }();
 
 ur_result_t urContextGetInfo(
-    ur_context_handle_t Context,       ///< [in] handle of the context
-    ur_context_info_t ContextInfoType, ///< [in] type of the info to retrieve
-    size_t PropSize,    ///< [in] the number of bytes of memory pointed to by
-                        ///< pContextInfo.
-    void *ContextInfo,  ///< [out][optional] array of bytes holding the info.
-                        ///< if propSize is not equal to or greater than the
-                        ///< real number of bytes needed to return the info then
-                        ///< the ::UR_RESULT_ERROR_INVALID_SIZE error is
-                        ///< returned and pContextInfo is not used.
-    size_t *PropSizeRet ///< [out][optional] pointer to the actual size in
-                        ///< bytes of data queried by ContextInfoType.
-) {
+    /// [in] handle of the context
+    ur_context_handle_t Context,
+    /// [in] type of the info to retrieve
+    ur_context_info_t ContextInfoType,
+    /// [in] the number of bytes of memory pointed to by pContextInfo.
+    size_t PropSize,
+    /// [out][optional] array of bytes holding the info. if propSize is not
+    /// equal to or greater than the real number of bytes needed to return the
+    /// info then the ::UR_RESULT_ERROR_INVALID_SIZE error is returned and
+    /// pContextInfo is not used.
+    void *ContextInfo,
+    /// [out][optional] pointer to the actual size in bytes of data queried by
+    /// ContextInfoType.
+    size_t *PropSizeRet) {
   std::shared_lock<ur_shared_mutex> Lock(Context->Mutex);
   UrReturnHelper ReturnValue(PropSize, ContextInfo, PropSizeRet);
   switch (
@@ -141,22 +143,22 @@ ur_result_t urContextGetInfo(
 }
 
 ur_result_t urContextGetNativeHandle(
-    ur_context_handle_t Context,      ///< [in] handle of the context.
-    ur_native_handle_t *NativeContext ///< [out] a pointer to the native
-                                      ///< handle of the context.
-) {
+    /// [in] handle of the context.
+    ur_context_handle_t Context,
+    /// [out] a pointer to the native handle of the context.
+    ur_native_handle_t *NativeContext) {
   *NativeContext = reinterpret_cast<ur_native_handle_t>(Context->ZeContext);
   return UR_RESULT_SUCCESS;
 }
 
 ur_result_t urContextCreateWithNativeHandle(
     ur_native_handle_t
-        NativeContext, ///< [in] the native handle of the context.
+        /// [in] the native handle of the context.
+        NativeContext,
     ur_adapter_handle_t, uint32_t NumDevices, const ur_device_handle_t *Devices,
     const ur_context_native_properties_t *Properties,
-    ur_context_handle_t
-        *Context ///< [out] pointer to the handle of the context object created.
-) {
+    /// [out] pointer to the handle of the context object created.
+    ur_context_handle_t *Context) {
   bool OwnNativeHandle = Properties->isNativeHandleOwned;
   try {
     ze_context_handle_t ZeContext =
@@ -174,12 +176,12 @@ ur_result_t urContextCreateWithNativeHandle(
 }
 
 ur_result_t urContextSetExtendedDeleter(
-    ur_context_handle_t Context, ///< [in] handle of the context.
-    ur_context_extended_deleter_t
-        Deleter,   ///< [in] Function pointer to extended deleter.
-    void *UserData ///< [in][out][optional] pointer to data to be passed to
-                   ///< callback.
-) {
+    /// [in] handle of the context.
+    ur_context_handle_t Context,
+    /// [in] Function pointer to extended deleter.
+    ur_context_extended_deleter_t Deleter,
+    /// [in][out][optional] pointer to data to be passed to callback.
+    void *UserData) {
   std::ignore = Context;
   std::ignore = Deleter;
   std::ignore = UserData;