Other minor C API doc fixes.

Author: Diptorup Deb

dpctl-capi/include/dpctl_sycl_device_interface.h

@@ -57,7 +57,8 @@ DPCTLDevice_Copy(__dpctl_keep const DPCTLSyclDeviceRef DRef);
  * @brief Returns a new DPCTLSyclDeviceRef opaque object wrapping a SYCL device
  * instance as a host device.
  *
- * @return   An opaque pointer to the host SYCL device.
+ * @return   An opaque pointer to a ``sycl::device`` created as an instance of
+ * the host device.
  * @ingroup DeviceInterface
  */
 DPCTL_API
@@ -67,7 +68,7 @@ __dpctl_give DPCTLSyclDeviceRef DPCTLDevice_Create();
  * @brief Returns a new DPCTLSyclDeviceRef opaque object created using the
  * provided device_selector.
  *
- * @param    DSRef          An opaque pointer to a SYCL device_selector.
+ * @param    DSRef          An opaque pointer to a ``sycl::device_selector``.
  * @return   Returns an opaque pointer to a SYCL device created using the
  *           device_selector, if the requested device could not be created a
  *           nullptr is returned.
@@ -88,9 +89,9 @@ void DPCTLDevice_Delete(__dpctl_take DPCTLSyclDeviceRef DRef);
 
 /*!
  * @brief Returns true if this SYCL device is an OpenCL device and the device
- * type is sycl::info::device_type::accelerator.
+ * type is ``sycl::info::device_type::accelerator``.
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return   True if the device type is an accelerator, else False.
  * @ingroup DeviceInterface
  */
@@ -99,9 +100,9 @@ bool DPCTLDevice_IsAccelerator(__dpctl_keep const DPCTLSyclDeviceRef DRef);
 
 /*!
  * @brief Returns true if this SYCL device is an OpenCL device and the device
- * type is sycl::info::device_type::cpu.
+ * type is ``sycl::info::device_type::cpu``.
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return   True if the device type is a cpu, else False.
  * @ingroup DeviceInterface
  */
@@ -110,9 +111,9 @@ bool DPCTLDevice_IsCPU(__dpctl_keep const DPCTLSyclDeviceRef DRef);
 
 /*!
  * @brief Returns true if this SYCL device is an OpenCL device and the device
- * type is sycl::info::device_type::gpu.
+ * type is ``sycl::info::device_type::gpu``.
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return    True if the device type is a gpu, else False.
  * @ingroup DeviceInterface
  */
@@ -122,7 +123,7 @@ bool DPCTLDevice_IsGPU(__dpctl_keep const DPCTLSyclDeviceRef DRef);
 /*!
  * @brief Returns true if this SYCL device is a host device.
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return   True if the device is a host device, else False.
  * @ingroup DeviceInterface
  */
@@ -132,9 +133,9 @@ bool DPCTLDevice_IsHost(__dpctl_keep const DPCTLSyclDeviceRef DRef);
 /*!
  * @brief Returns the backend for the device.
  *
- * @param    DRef           Opaque pointer to a sycl::device
- * @return   A DPCTLSyclBackendType enum value representing the sycl::backend
- * for the device.
+ * @param    DRef           Opaque pointer to a ``sycl::device``
+ * @return   A DPCTLSyclBackendType enum value representing the
+ * ``sycl::backend`` for the device.
  * @ingroup DeviceInterface
  */
 DPCTL_API
@@ -156,7 +157,7 @@ DPCTLDevice_GetDeviceType(__dpctl_keep const DPCTLSyclDeviceRef DRef);
 /*!
  * @brief Returns the OpenCL software driver version as a C string.
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return   A C string in the form major_number.minor.number that corresponds
  *           to the OpenCL driver version if this is a OpenCL device.
  * @ingroup DeviceInterface
@@ -168,7 +169,7 @@ DPCTLDevice_GetDriverInfo(__dpctl_keep const DPCTLSyclDeviceRef DRef);
 /*!
  * @brief Wrapper over device.get_info<info::device::max_compute_units>().
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return   Returns the valid result if device exists else returns 0.
  * @ingroup DeviceInterface
  */
@@ -179,7 +180,7 @@ DPCTLDevice_GetMaxComputeUnits(__dpctl_keep const DPCTLSyclDeviceRef DRef);
 /*!
  * @brief Wrapper for get_info<info::device::max_work_item_dimensions>().
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return   Returns the valid result if device exists else returns 0.
  * @ingroup DeviceInterface
  */
@@ -190,7 +191,7 @@ DPCTLDevice_GetMaxWorkItemDims(__dpctl_keep const DPCTLSyclDeviceRef DRef);
 /*!
  * @brief Wrapper for get_info<info::device::max_work_item_sizes>().
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return   Returns the valid result if device exists else returns NULL.
  * @ingroup DeviceInterface
  */
@@ -201,7 +202,7 @@ DPCTLDevice_GetMaxWorkItemSizes(__dpctl_keep const DPCTLSyclDeviceRef DRef);
 /*!
  * @brief Wrapper for get_info<info::device::max_work_group_size>().
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return   Returns the valid result if device exists else returns 0.
  * @ingroup DeviceInterface
  */
@@ -212,7 +213,7 @@ DPCTLDevice_GetMaxWorkGroupSize(__dpctl_keep const DPCTLSyclDeviceRef DRef);
 /*!
  * @brief Wrapper over device.get_info<info::device::max_num_sub_groups>.
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return   Returns the valid result if device exists else returns 0.
  * @ingroup DeviceInterface
  */
@@ -221,10 +222,10 @@ uint32_t
 DPCTLDevice_GetMaxNumSubGroups(__dpctl_keep const DPCTLSyclDeviceRef DRef);
 
 /*!
- * @brief Returns the sycl::platform for the device as DPCTLSyclPlatformRef
+ * @brief Returns the ``sycl::platform`` for the device as DPCTLSyclPlatformRef
  * opaque pointer.
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return   An opaque pointer to the sycl::platform for the device.
  * @ingroup DeviceInterface
  */
@@ -235,7 +236,7 @@ DPCTLDevice_GetPlatform(__dpctl_keep const DPCTLSyclDeviceRef DRef);
 /*!
  * @brief Returns a C string for the device name.
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return   A C string containing the OpenCL device name.
  * @ingroup DeviceInterface
  */
@@ -246,7 +247,7 @@ DPCTLDevice_GetName(__dpctl_keep const DPCTLSyclDeviceRef DRef);
 /*!
  * @brief Returns a C string corresponding to the vendor name.
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return    A C string containing the OpenCL device vendor name.
  * @ingroup DeviceInterface
  */
@@ -258,7 +259,7 @@ DPCTLDevice_GetVendorName(__dpctl_keep const DPCTLSyclDeviceRef DRef);
  * @brief Returns True if the device and the host share a unified memory
  * subsystem, else returns False.
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return   Boolean indicating if the device shares a unified memory subsystem
  * with the host.
  * @ingroup DeviceInterface
@@ -271,8 +272,8 @@ bool DPCTLDevice_IsHostUnifiedMemory(
  * @brief Checks if two DPCTLSyclDeviceRef objects point to the same
  * sycl::device.
  *
- * @param    DRef1         First opaque pointer to a sycl device.
- * @param    DRef2         Second opaque pointer to a sycl device.
+ * @param    DRef1         First opaque pointer to a ``sycl::device``.
+ * @param    DRef2         Second opaque pointer to a ``sycl::device``.
  * @return   True if the underlying sycl::device are same, false otherwise.
  * @ingroup DeviceInterface
  */
@@ -283,8 +284,8 @@ bool DPCTLDevice_AreEq(__dpctl_keep const DPCTLSyclDeviceRef DRef1,
 /*!
  * @brief Checks if device has aspect.
  *
- * @param    DRef       Opaque pointer to a sycl::device
- * @param    AT         DPCTLSyclAspectType of device::aspect.
+ * @param    DRef       Opaque pointer to a ``sycl::device``
+ * @param    AT         DPCTLSyclAspectType of ``device::aspect``.
  * @return   True if sycl::device has device::aspect, else false.
  * @ingroup DeviceInterface
  */
@@ -391,7 +392,7 @@ DPCTLDevice_GetImage3dMaxDepth(__dpctl_keep const DPCTLSyclDeviceRef DRef);
  * units is not evenly divided by count, then the remaining compute units are
  * not included in any of the sub devices.
  *
- * @param    DRef         Opaque pointer to a sycl::device
+ * @param    DRef         Opaque pointer to a ``sycl::device``
  * @param    count        Count compute units that need to contains in
  * subdevices
  * @return   A #DPCTLDeviceVectorRef containing #DPCTLSyclDeviceRef objects
@@ -408,7 +409,7 @@ DPCTLDevice_CreateSubDevicesEqually(__dpctl_keep const DPCTLSyclDeviceRef DRef,
  * non-zero value M in the counts vector, a sub device with M compute units
  * is created.
  *
- * @param    DRef         Opaque pointer to a sycl::device
+ * @param    DRef         Opaque pointer to a ``sycl::device``
  * @param    counts       Array with count compute units
  * that need to contains in subdevices
  * @param    ncounts      Number of counts
@@ -457,7 +458,7 @@ bool DPCTLDevice_GetSubGroupIndependentForwardProgress(
  * @brief Wrapper over
  * device.get_info<info::device::preferred_vector_width_char>.
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return   Returns the preferred native vector width size for built-in scalar
  * types that can be put into vectors.
  * @ingroup DeviceInterface
@@ -470,7 +471,7 @@ uint32_t DPCTLDevice_GetPreferredVectorWidthChar(
  * @brief Wrapper over
  * device.get_info<info::device::preferred_vector_width_short>.
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return   Returns the preferred native vector width size for built-in scalar
  * types that can be put into vectors.
  * @ingroup DeviceInterface
@@ -483,7 +484,7 @@ uint32_t DPCTLDevice_GetPreferredVectorWidthShort(
  * @brief Wrapper over
  * device.get_info<info::device::preferred_vector_width_int>.
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return   Returns the preferred native vector width size for built-in scalar
  * types that can be put into vectors.
  * @ingroup DeviceInterface
@@ -496,7 +497,7 @@ uint32_t DPCTLDevice_GetPreferredVectorWidthInt(
  * @brief Wrapper over
  * device.get_info<info::device::preferred_vector_width_long>.
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return   Returns the preferred native vector width size for built-in scalar
  * types that can be put into vectors.
  * @ingroup DeviceInterface
@@ -509,7 +510,7 @@ uint32_t DPCTLDevice_GetPreferredVectorWidthLong(
  * @brief Wrapper over
  * device.get_info<info::device::preferred_vector_width_float>.
  *
- * @param    DRef           Opaque pointer
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return   Returns the preferred native vector width size for built-in scalar
  * type.
  * @ingroup DeviceInterface
@@ -522,7 +523,7 @@ uint32_t DPCTLDevice_GetPreferredVectorWidthFloat(
  * @brief Wrapper over
  * device.get_info<info::device::preferred_vector_width_double>.
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return   Returns the preferred native vector width size for built-in scalar
  * types that can be put into vectors.
  * @ingroup DeviceInterface
@@ -533,9 +534,9 @@ uint32_t DPCTLDevice_GetPreferredVectorWidthDouble(
 
 /*!
  * @brief Wrapper over
- * device.get_info<info::device::preferred_vector_width_half>.
+ * ``device.get_info<info::device::preferred_vector_width_half>``.
  *
- * @param    DRef           Opaque pointer to a sycl::device
+ * @param    DRef           Opaque pointer to a ``sycl::device``
  * @return   Returns the preferred native vector width size for built-in scalar
  * types that can be put into vectors.
  * @ingroup DeviceInterface