Fix the docstrings for some of the SyclDevice aspect properties.

Author: Diptorup Deb

dpctl/_sycl_device.pyx

@@ -373,7 +373,7 @@ cdef class SyclDevice(_SyclDevice):
         Returns:
             device_type: The type of device encoded as a device_type enum.
         Raises:
-            A ValueError is raised if the device type is not recognized.
+            ValueError: If the device type is not recognized.
         """
         cdef _device_type DTy = (
             DPCTLDevice_GetDeviceType(self._device_ref)
@@ -393,116 +393,199 @@ cdef class SyclDevice(_SyclDevice):
 
     @property
     def has_aspect_host(self):
-        "Returns True if this device is a host device, False otherwise"
+        """ Returns True if this device is a host device, False otherwise.
+
+        Returns:
+            bool: Indicates if the device is a host device.
+        """
         cdef _aspect_type AT = _aspect_type._host
         return DPCTLDevice_HasAspect(self._device_ref, AT)
 
     @property
     def has_aspect_cpu(self):
-        "Returns True if this device is a CPU device, False otherwise"
+        """ Returns True if this device is a CPU device, False otherwise.
+
+        Returns:
+            bool: Indicates if the device is a cpu.
+        """
         cdef _aspect_type AT = _aspect_type._cpu
         return DPCTLDevice_HasAspect(self._device_ref, AT)
 
     @property
     def has_aspect_gpu(self):
-        "Returns True if this device is a GPU device, False otherwise"
+        """ Returns True if this device is a GPU device, False otherwise.
+
+        Returns:
+            bool: Indicates if the device is a gpu.
+        """
         cdef _aspect_type AT = _aspect_type._gpu
         return DPCTLDevice_HasAspect(self._device_ref, AT)
 
     @property
     def has_aspect_accelerator(self):
-        "Returns True if this device is an accelerator device, False otherwise"
+        """ Returns True if this device is an accelerator device, False
+        otherwise.
+
+        SYCL considers an accelerator to be a device that usually uses a
+        peripheral interconnect for communication.
+
+        Returns:
+            bool: Indicates if the device is an accelerator.
+        """
         cdef _aspect_type AT = _aspect_type._accelerator
         return DPCTLDevice_HasAspect(self._device_ref, AT)
 
     @property
     def has_aspect_custom(self):
-        "Returns True if this device is a custom device, False otherwise"
+        """ Returns True if this device is a custom device, False otherwise.
+
+        A custom device can be a dedicated accelerator that can use the
+        SYCL API, but programmable kernels cannot be dispatched to the device,
+        only fixed functionality is available. Refer SYCL spec for more details.
+
+        Returns:
+            bool: Indicates if the device is a custom SYCL device.
+        """
         cdef _aspect_type AT = _aspect_type._custom
         return DPCTLDevice_HasAspect(self._device_ref, AT)
 
     @property
     def has_aspect_fp16(self):
-        """ Returns True if kernels submitted to this device
-        may use 16-bit floating point types, False otherwise
+        """ Returns True if the device supports half-precision floating point
+        operations, False otherwise.
+
+        Returns:
+            bool: Indicates that the device supports half precision floating
+            point operations.
         """
         cdef _aspect_type AT = _aspect_type._fp16
         return DPCTLDevice_HasAspect(self._device_ref, AT)
 
     @property
     def has_aspect_fp64(self):
-        """  Returns True if kernels submitted to this device
-        may use 64-bit floating point types, False otherwise
+        """ Returns True if the device supports 64-bit precision floating point
+        operations, False otherwise.
+
+        Returns:
+            bool: Indicates that the device supports 64-bit precision floating
+            point operations.
         """
         cdef _aspect_type AT = _aspect_type._fp64
         return DPCTLDevice_HasAspect(self._device_ref, AT)
 
     @property
     def has_aspect_atomic64(self):
-        """ Returns True if kernels submitted to this device
-        may perform 64-bit atomic operations, False otherwise
+        """ Returns true if the device supports a basic set of atomic
+        operations, False otherwise.
+
+        Indicates that the device supports the following atomic operations on
+        64-bit values:
+            - atomic::load
+            - atomic::store
+            - atomic::fetch_add
+            - atomic::fetch_sub
+            - atomic::exchange
+            - atomic::compare_exchange_strong
+            - atomic::compare_exchange_weak
+
+        Returns:
+            bool: Indicates that the device supports a basic set of atomic
+            operations on 64-bit values.
         """
         cdef _aspect_type AT = _aspect_type._atomic64
         return DPCTLDevice_HasAspect(self._device_ref, AT)
 
     @property
     def has_aspect_image(self):
-        """ Returns True if this device supports images, False otherwise
+        """ Returns True if the device supports images, False otherwise (refer
+        Sec 4.7.3 of SYCL 2020 spec).
+
+        Returns:
+            bool: Indicates that the device supports images
         """
         cdef _aspect_type AT = _aspect_type._image
         return DPCTLDevice_HasAspect(self._device_ref, AT)
 
     @property
     def has_aspect_online_compiler(self):
         """ Returns True if this device supports online compilation of
-        device code, False otherwise
+        device code, False otherwise.
+
+        Returns:
+            bool: Indicates that the device supports online compilation of
+            device code.
         """
         cdef _aspect_type AT = _aspect_type._online_compiler
         return DPCTLDevice_HasAspect(self._device_ref, AT)
 
     @property
     def has_aspect_online_linker(self):
         """ Returns True if this device supports online linking of
-        device code, False otherwise
+        device code, False otherwise.
+
+        Returns:
+            bool: Indicates that the device supports online linking of device
+            code.
         """
         cdef _aspect_type AT = _aspect_type._online_linker
         return DPCTLDevice_HasAspect(self._device_ref, AT)
 
     @property
     def has_aspect_queue_profiling(self):
         """ Returns True if this device supports queue profiling,
-        False otherwise
+        False otherwise.
+
+        Returns:
+            bool: Indicates that the device supports queue profiling.
         """
         cdef _aspect_type AT = _aspect_type._queue_profiling
         return DPCTLDevice_HasAspect(self._device_ref, AT)
 
     @property
     def has_aspect_usm_device_allocations(self):
         """ Returns True if this device supports explicit USM allocations,
-        False otherwise
+        False otherwise (refer Siction 4.8 of SYCL 2020 specs).
+
+        Returns:
+            bool: Indicates that the device supports explicit USM allocations.
         """
         cdef _aspect_type AT = _aspect_type._usm_device_allocations
         return DPCTLDevice_HasAspect(self._device_ref, AT)
 
     @property
     def has_aspect_usm_host_allocations(self):
         """ Returns True if this device can access USM-host memory,
-        False otherwise
+        False otherwise (refer Siction 4.8 of SYCL 2020 specs).
+
+        Returns:
+            bool: Indicates that the device can access USM memory
+            allocated via ``usm::alloc::host``.
         """
         cdef _aspect_type AT = _aspect_type._usm_host_allocations
         return DPCTLDevice_HasAspect(self._device_ref, AT)
 
     @property
     def has_aspect_usm_shared_allocations(self):
         """ Returns True if this device supports USM-shared memory
-        allocated on the same device, False otherwise
+        allocated on the same device, False otherwise.
+
+        Returns:
+            bool: Indicates that the device supports USM memory
+            allocated via ``usm::alloc::shared``.
         """
         cdef _aspect_type AT = _aspect_type._usm_shared_allocations
         return DPCTLDevice_HasAspect(self._device_ref, AT)
 
     @property
     def has_aspect_usm_restricted_shared_allocations(self):
-        """ Deprecated property, do not use.
+        """ Returns True if this device supports USM memory
+        allocated as restricted USM, False otherwise.
+
+        Returns:
+            bool: Indicates that the device supports USM memory allocated via
+            ``usm::alloc::shared`` as restricted USM.
+
+        .. deprecated:: 0.14
         """
         cdef _aspect_type AT = _aspect_type._usm_restricted_shared_allocations
         return DPCTLDevice_HasAspect(self._device_ref, AT)
@@ -511,7 +594,11 @@ cdef class SyclDevice(_SyclDevice):
     def has_aspect_usm_system_allocations(self):
         """ Returns True if system allocator may be used instead of SYCL USM
         allocation mechanism for USM-shared allocations on this device,
-        False otherwise
+        False otherwise.
+
+        Returns:
+            bool: Indicates that system allocator may be used instead of SYCL
+            ``usm::alloc::shared``.
         """
         cdef _aspect_type AT = _aspect_type._usm_system_allocations
         return DPCTLDevice_HasAspect(self._device_ref, AT)
@@ -650,6 +737,9 @@ cdef class SyclDevice(_SyclDevice):
     def max_work_item_dims(self):
         """ Returns the maximum dimensions that specify the global and local
         work-item IDs used by the data parallel execution model.
+
+        Returns:
+            int: The maximum number of work items supported by the device.
         """
         cdef uint32_t max_work_item_dims = 0
         max_work_item_dims = DPCTLDevice_GetMaxWorkItemDims(self._device_ref)
@@ -659,8 +749,12 @@ cdef class SyclDevice(_SyclDevice):
     def max_work_item_sizes1d(self):
         """ Returns the maximum number of work-items that are permitted in each
         dimension of the work-group of the nd_range<1>. The minimum value is
-        `(1 )` for devices that are not of device type
-         ``info::device_type::custom``.
+        `(1 )` for devices that evaluate to False for
+        :py:attr:`~has_aspect_custom`.
+
+        Returns:
+            tuple[int,]: A tuple with the maximum allowed value for a 1D range
+            used to enqueue a kernel on the device.
         """
         cdef size_t *max_work_item_sizes1d = NULL
         max_work_item_sizes1d = DPCTLDevice_GetMaxWorkItemSizes1d(
@@ -674,8 +768,12 @@ cdef class SyclDevice(_SyclDevice):
     def max_work_item_sizes2d(self):
         """ Returns the maximum number of work-items that are permitted in each
         dimension of the work-group of the nd_range<2>. The minimum value is
-        `(1; 1)` for devices that are not of device type
-         ``info::device_type::custom``.
+        `(1; 1)` for devices that evaluate to False for
+        :py:attr:`~has_aspect_custom`.
+
+        Returns:
+            tuple[int, int]: A tuple with the maximum allowed value for each
+            dimension of a 2D range used to enqueue a kernel on the device.
         """
         cdef size_t *max_work_item_sizes2d = NULL
         max_work_item_sizes2d = DPCTLDevice_GetMaxWorkItemSizes2d(
@@ -689,8 +787,12 @@ cdef class SyclDevice(_SyclDevice):
     def max_work_item_sizes3d(self):
         """ Returns the maximum number of work-items that are permitted in each
         dimension of the work-group of the nd_range<3>. The minimum value is
-        `(1; 1; 1)` for devices that are not of device type
-         ``info::device_type::custom``.
+        `(1; 1; 1)` for devices that evaluate to False for
+        :py:attr:`~has_aspect_custom`.
+
+        Returns:
+            tuple[int, int, int]: A tuple with the maximum allowed value for
+            each dimension of a 3D range used to enqueue a kernel on the device.
         """
         return (
             self._max_work_item_sizes[0],
@@ -702,8 +804,16 @@ cdef class SyclDevice(_SyclDevice):
     def max_work_item_sizes(self):
         """ Returns the maximum number of work-items that are permitted in each
         dimension of the work-group of the nd_range. The minimum value is
-        `(1; 1; 1)` for devices that are not of device type
-        ``info::device_type::custom``.
+        `(1; 1; 1)` for devices that evaluate to False for
+        :py:attr:`~has_aspect_custom`.
+
+        Returns:
+            tuple[int, int, int]: A tuple whose length depends on the number of
+            workgrpup dimensions supported by the device.
+
+        .. deprecated:: 0.14
+           The property is deprecated use :py:attr:`~max_work_item_sizes3d`
+           instead.
         """
         warnings.warn(
             "dpctl.SyclDevice.max_work_item_sizes is deprecated, "
@@ -720,17 +830,22 @@ cdef class SyclDevice(_SyclDevice):
     def max_compute_units(self):
         """ Returns the number of parallel compute units available to the
         device. The minimum value is 1.
+
+        Returns:
+            int: The number of compute units in the device.
         """
         cdef uint32_t max_compute_units = 0
         max_compute_units = DPCTLDevice_GetMaxComputeUnits(self._device_ref)
         return max_compute_units
 
     @property
     def max_work_group_size(self):
-        """ Returns the maximum number of work-items
-        that are permitted in a work-group executing a
-        kernel on a single compute unit. The minimum
+        """ Returns the maximum number of work-items that are permitted in a
+        work-group executing a kernel on a single compute unit. The minimum
         value is 1.
+
+        Returns:
+            int: The maximum supported work group size.
         """
         cdef uint32_t max_work_group_size = 0
         max_work_group_size = DPCTLDevice_GetMaxWorkGroupSize(self._device_ref)
@@ -755,8 +870,12 @@ cdef class SyclDevice(_SyclDevice):
 
     @property
     def sub_group_independent_forward_progress(self):
-        """ Returns true if the device supports independent forward progress of
+        """ Returns True if the device supports independent forward progress of
         sub-groups with respect to other sub-groups in the same work-group.
+
+        Returns:
+            bool: Indicates if the device supports independent forward progress
+            of sub-groups.
         """
         return DPCTLDevice_GetSubGroupIndependentForwardProgress(
             self._device_ref
@@ -1109,8 +1228,7 @@ cdef class SyclDevice(_SyclDevice):
         Returns:
             global_mem_cache_type: type of cache memory
         Raises:
-            A RuntimeError is raised if an unrecognized memory type
-            is reported by runtime.
+            RuntimeError: If an unrecognized memory type is reported by runtime.
         """
         cdef _global_mem_cache_type gmcTy = (
            DPCTLDevice_GetGlobalMemCacheType(self._device_ref)