[SYCL][NFC] Fix doxygen warnings (#1270)

* Change doxygen comments style
  JAVADOC -> C/C++ style
  Fix one typo: @retun -> \return

* The warnings are about parameter name mismatch and undocumented
parameters.

Signed-off-by: Alexey Bader <[email protected]>

Author: bader

sycl/include/CL/sycl/context.hpp

@@ -32,8 +32,8 @@ class context {
   /// The constructed SYCL context will use the AsyncHandler parameter to handle
   /// exceptions.
   ///
-  /// @param AsyncHandler is an instance of async_handler.
-  /// @param UseCUDAPrimaryContext is a bool determining whether to use the
+  /// \param AsyncHandler is an instance of async_handler.
+  /// \param UseCUDAPrimaryContext is a bool determining whether to use the
   ///        primary context in the CUDA backend.
   explicit context(const async_handler &AsyncHandler = {},
                    bool UseCUDAPrimaryContext = false);
@@ -45,9 +45,9 @@ class context {
   /// The constructed SYCL context will use the AsyncHandler parameter to handle
   /// exceptions.
   ///
-  /// @param Device is an instance of SYCL device.
-  /// @param AsyncHandler is an instance of async_handler.
-  /// @param UseCUDAPrimaryContext is a bool determining whether to use the
+  /// \param Device is an instance of SYCL device.
+  /// \param AsyncHandler is an instance of async_handler.
+  /// \param UseCUDAPrimaryContext is a bool determining whether to use the
   ///        primary context in the CUDA backend.
   explicit context(const device &Device, async_handler AsyncHandler = {},
                    bool UseCUDAPrimaryContext = false);
@@ -59,9 +59,9 @@ class context {
   /// The constructed SYCL context will use the AsyncHandler parameter to handle
   /// exceptions.
   ///
-  /// @param Platform is an instance of SYCL platform.
-  /// @param AsyncHandler is an instance of async_handler.
-  /// @param UseCUDAPrimaryContext is a bool determining whether to use the
+  /// \param Platform is an instance of SYCL platform.
+  /// \param AsyncHandler is an instance of async_handler.
+  /// \param UseCUDAPrimaryContext is a bool determining whether to use the
   ///        primary context in the CUDA backend.
   explicit context(const platform &Platform, async_handler AsyncHandler = {},
                    bool UseCUDAPrimaryContext = false);
@@ -74,9 +74,9 @@ class context {
   /// The constructed SYCL context will use the AsyncHandler parameter to handle
   /// exceptions.
   ///
-  /// @param DeviceList is a list of SYCL device instances.
-  /// @param AsyncHandler is an instance of async_handler.
-  /// @param UseCUDAPrimaryContext is a bool determining whether to use the
+  /// \param DeviceList is a list of SYCL device instances.
+  /// \param AsyncHandler is an instance of async_handler.
+  /// \param UseCUDAPrimaryContext is a bool determining whether to use the
   ///        primary context in the CUDA backend.
   explicit context(const vector_class<device> &DeviceList,
                    async_handler AsyncHandler = {},
@@ -88,8 +88,8 @@ class context {
   /// The constructed SYCL context will use the AsyncHandler parameter to handle
   /// exceptions.
   ///
-  /// @param ClContext is an instance of OpenCL cl_context.
-  /// @param AsyncHandler is an instance of async_handler.
+  /// \param ClContext is an instance of OpenCL cl_context.
+  /// \param AsyncHandler is an instance of async_handler.
   context(cl_context ClContext, async_handler AsyncHandler = {});
 
   /// Queries this SYCL context for information.
@@ -115,22 +115,22 @@ class context {
   ///
   /// The OpenCL cl_context handle is retained on return.
   ///
-  /// @return a valid instance of OpenCL cl_context.
+  /// \return a valid instance of OpenCL cl_context.
   cl_context get() const;
 
   /// Checks if this context is a SYCL host context.
   ///
-  /// @return true if this context is a SYCL host context.
+  /// \return true if this context is a SYCL host context.
   bool is_host() const;
 
   /// Gets platform associated with this SYCL context.
   ///
-  /// @return a valid instance of SYCL platform.
+  /// \return a valid instance of SYCL platform.
   platform get_platform() const;
 
   /// Gets devices associated with this SYCL context.
   ///
-  /// @return a vector of valid SYCL device instances.
+  /// \return a vector of valid SYCL device instances.
   vector_class<device> get_devices() const;
 
 private:

sycl/include/CL/sycl/detail/host_profiling_info.hpp

@@ -22,11 +22,11 @@ class HostProfilingInfo {
 public:
   /// Returns event's start time.
   ///
-  /// @return event's start time in nanoseconds.
+  /// \return event's start time in nanoseconds.
   cl_ulong getStartTime() const { return StartTime; }
   /// Returns event's end time.
   ///
-  /// @return event's end time in nanoseconds.
+  /// \return event's end time in nanoseconds.
   cl_ulong getEndTime() const { return EndTime; }
 
   /// Measures event's start time.

sycl/include/CL/sycl/detail/pi.h

@@ -788,20 +788,20 @@ pi_result piKernelRelease(pi_kernel kernel);
 /// Sets up pointer arguments for CL kernels. An extra indirection
 /// is required due to CL argument conventions.
 ///
-/// @param kernel is the kernel to be launched
-/// @param arg_index is the index of the kernel argument
-/// @param arg_size is the size in bytes of the argument (ignored in CL)
-/// @param arg_value is the pointer argument
+/// \param kernel is the kernel to be launched
+/// \param arg_index is the index of the kernel argument
+/// \param arg_size is the size in bytes of the argument (ignored in CL)
+/// \param arg_value is the pointer argument
 pi_result piextKernelSetArgPointer(pi_kernel kernel, pi_uint32 arg_index,
                                    size_t arg_size, const void *arg_value);
 
 /// API to set attributes controlling kernel execution
 ///
-/// @param kernel is the pi kernel to execute
-/// @param param_name is a pi_kernel_exec_info value that specifies the info
+/// \param kernel is the pi kernel to execute
+/// \param param_name is a pi_kernel_exec_info value that specifies the info
 ///        passed to the kernel
-/// @param param_value_size is the size of the value in bytes
-/// @param param_value is a pointer to the value to set for the kernel
+/// \param param_value_size is the size of the value in bytes
+/// \param param_value is a pointer to the value to set for the kernel
 ///
 /// If param_name is PI_USM_INDIRECT_ACCESS, the value will be a ptr to
 ///    the pi_bool value PI_TRUE
@@ -1025,73 +1025,73 @@ typedef _pi_usm_migration_flags pi_usm_migration_flags;
 
 /// Allocates host memory accessible by the device.
 ///
-/// @param result_ptr contains the allocated memory
-/// @param context is the pi_context
-/// @param pi_usm_mem_properties are optional allocation properties
-/// @param size_t is the size of the allocation
-/// @param alignment is the desired alignment of the allocation
+/// \param result_ptr contains the allocated memory
+/// \param context is the pi_context
+/// \param pi_usm_mem_properties are optional allocation properties
+/// \param size_t is the size of the allocation
+/// \param alignment is the desired alignment of the allocation
 pi_result piextUSMHostAlloc(void **result_ptr, pi_context context,
                             pi_usm_mem_properties *properties, size_t size,
                             pi_uint32 alignment);
 
 /// Allocates device memory
 ///
-/// @param result_ptr contains the allocated memory
-/// @param context is the pi_context
-/// @param device is the device the memory will be allocated on
-/// @param pi_usm_mem_properties are optional allocation properties
-/// @param size_t is the size of the allocation
-/// @param alignment is the desired alignment of the allocation
+/// \param result_ptr contains the allocated memory
+/// \param context is the pi_context
+/// \param device is the device the memory will be allocated on
+/// \param pi_usm_mem_properties are optional allocation properties
+/// \param size_t is the size of the allocation
+/// \param alignment is the desired alignment of the allocation
 pi_result piextUSMDeviceAlloc(void **result_ptr, pi_context context,
                               pi_device device,
                               pi_usm_mem_properties *properties, size_t size,
                               pi_uint32 alignment);
 
 /// Allocates memory accessible on both host and device
 ///
-/// @param result_ptr contains the allocated memory
-/// @param context is the pi_context
-/// @param device is the device the memory will be allocated on
-/// @param pi_usm_mem_properties are optional allocation properties
-/// @param size_t is the size of the allocation
-/// @param alignment is the desired alignment of the allocation
+/// \param result_ptr contains the allocated memory
+/// \param context is the pi_context
+/// \param device is the device the memory will be allocated on
+/// \param pi_usm_mem_properties are optional allocation properties
+/// \param size_t is the size of the allocation
+/// \param alignment is the desired alignment of the allocation
 pi_result piextUSMSharedAlloc(void **result_ptr, pi_context context,
                               pi_device device,
                               pi_usm_mem_properties *properties, size_t size,
                               pi_uint32 alignment);
 
 /// Frees allocated USM memory
 ///
-/// @param context is the pi_context of the allocation
-/// @param ptr is the memory to be freed
+/// \param context is the pi_context of the allocation
+/// \param ptr is the memory to be freed
 pi_result piextUSMFree(pi_context context, void *ptr);
 
 /// USM Memset API
 ///
-/// @param queue is the queue to submit to
-/// @param ptr is the ptr to memset
-/// @param value is value to set.  It is interpreted as an 8-bit value and the
+/// \param queue is the queue to submit to
+/// \param ptr is the ptr to memset
+/// \param value is value to set.  It is interpreted as an 8-bit value and the
 /// upper
 ///        24 bits are ignored
-/// @param count is the size in bytes to memset
-/// @param num_events_in_waitlist is the number of events to wait on
-/// @param events_waitlist is an array of events to wait on
-/// @param event is the event that represents this operation
+/// \param count is the size in bytes to memset
+/// \param num_events_in_waitlist is the number of events to wait on
+/// \param events_waitlist is an array of events to wait on
+/// \param event is the event that represents this operation
 pi_result piextUSMEnqueueMemset(pi_queue queue, void *ptr, pi_int32 value,
                                 size_t count, pi_uint32 num_events_in_waitlist,
                                 const pi_event *events_waitlist,
                                 pi_event *event);
 
 /// USM Memcpy API
 ///
-/// @param queue is the queue to submit to
-/// @param blocking is whether this operation should block the host
-/// @param src_ptr is the data to be copied
-/// @param dst_ptr is the location the data will be copied
-/// @param size is number of bytes to copy
-/// @param num_events_in_waitlist is the number of events to wait on
-/// @param events_waitlist is an array of events to wait on
-/// @param event is the event that represents this operation
+/// \param queue is the queue to submit to
+/// \param blocking is whether this operation should block the host
+/// \param src_ptr is the data to be copied
+/// \param dst_ptr is the location the data will be copied
+/// \param size is number of bytes to copy
+/// \param num_events_in_waitlist is the number of events to wait on
+/// \param events_waitlist is an array of events to wait on
+/// \param event is the event that represents this operation
 pi_result piextUSMEnqueueMemcpy(pi_queue queue, pi_bool blocking, void *dst_ptr,
                                 const void *src_ptr, size_t size,
                                 pi_uint32 num_events_in_waitlist,
@@ -1100,13 +1100,13 @@ pi_result piextUSMEnqueueMemcpy(pi_queue queue, pi_bool blocking, void *dst_ptr,
 
 /// Hint to migrate memory to the device
 ///
-/// @param queue is the queue to submit to
-/// @param ptr points to the memory to migrate
-/// @param size is the number of bytes to migrate
-/// @param flags is a bitfield used to specify memory migration options
-/// @param num_events_in_waitlist is the number of events to wait on
-/// @param events_waitlist is an array of events to wait on
-/// @param event is the event that represents this operation
+/// \param queue is the queue to submit to
+/// \param ptr points to the memory to migrate
+/// \param size is the number of bytes to migrate
+/// \param flags is a bitfield used to specify memory migration options
+/// \param num_events_in_waitlist is the number of events to wait on
+/// \param events_waitlist is an array of events to wait on
+/// \param event is the event that represents this operation
 pi_result piextUSMEnqueuePrefetch(pi_queue queue, const void *ptr, size_t size,
                                   pi_usm_migration_flags flags,
                                   pi_uint32 num_events_in_waitlist,
@@ -1115,11 +1115,11 @@ pi_result piextUSMEnqueuePrefetch(pi_queue queue, const void *ptr, size_t size,
 
 /// USM Memadvise API
 ///
-/// @param queue is the queue to submit to
-/// @param ptr is the data to be advised
-/// @param length is the size in bytes of the memory to advise
-/// @param advice is device specific advice
-/// @param event is the event that represents this operation
+/// \param queue is the queue to submit to
+/// \param ptr is the data to be advised
+/// \param length is the size in bytes of the memory to advise
+/// \param advice is device specific advice
+/// \param event is the event that represents this operation
 // USM memadvise API to govern behavior of automatic migration mechanisms
 pi_result piextUSMEnqueueMemAdvise(pi_queue queue, const void *ptr,
                                    size_t length, int advice, pi_event *event);
@@ -1134,12 +1134,12 @@ pi_result piextUSMEnqueueMemAdvise(pi_queue queue, const void *ptr,
 ///                     allocation is in bytes. Result is a size_t.
 ///   PI_MEM_ALLOC_DEVICE returns the pi_device this was allocated against
 ///
-/// @param context is the pi_context
-/// @param ptr is the pointer to query
-/// @param param_name is the type of query to perform
-/// @param param_value_size is the size of the result in bytes
-/// @param param_value is the result
-/// @param param_value_ret is how many bytes were written
+/// \param context is the pi_context
+/// \param ptr is the pointer to query
+/// \param param_name is the type of query to perform
+/// \param param_value_size is the size of the result in bytes
+/// \param param_value is the result
+/// \param param_value_ret is how many bytes were written
 pi_result piextUSMGetMemAllocInfo(pi_context context, const void *ptr,
                                   pi_mem_info param_name,
                                   size_t param_value_size, void *param_value,