Merge pull request #1414 from IntelPython/docs/improve-doc-strings

Improve docstring for kernel_api functions. af226f3

dev/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 77c7ed92725ec04ee213bdd81322e999
+config: 63040eaeab372d0bca2060603001fe58
 tags: 645f666f9bcd5a90fca523b33c5a78b7

dev/_sources/autoapi/numba_dpex/core/boxing/index.rst.txt

@@ -24,15 +24,15 @@ Overview
    * - :py:obj:`RangeType <numba_dpex.core.boxing.RangeType>`
      - Numba-dpex type corresponding to
    * - :py:obj:`NdRange <numba_dpex.core.boxing.NdRange>`
-     - A class to encapsulate all kernel launch parameters.
+     - Analogue to the :sycl_ndrange:`sycl::nd_range <>` class.
    * - :py:obj:`Range <numba_dpex.core.boxing.Range>`
-     - A data structure to encapsulate a single kernel launch parameter.
+     - Analogue to the :sycl_range:`sycl::range <>` class.
    * - :py:obj:`USMNdArray <numba_dpex.core.boxing.USMNdArray>`
      - A type class to represent dpctl.tensor.usm_ndarray.
    * - :py:obj:`NdRange <numba_dpex.core.boxing.NdRange>`
-     - A class to encapsulate all kernel launch parameters.
+     - Analogue to the :sycl_ndrange:`sycl::nd_range <>` class.
    * - :py:obj:`Range <numba_dpex.core.boxing.Range>`
-     - A data structure to encapsulate a single kernel launch parameter.
+     - Analogue to the :sycl_range:`sycl::range <>` class.
 
 
 .. list-table:: Function
@@ -80,7 +80,7 @@ Classes
 
 .. py:class:: NdRange(global_size, local_size)
 
-   A class to encapsulate all kernel launch parameters.
+   Analogue to the :sycl_ndrange:`sycl::nd_range <>` class.
 
    The NdRange defines the index space for a work group as well as
    the global index space. It is passed to parallel_for to execute
@@ -131,7 +131,7 @@ Classes
 
    Bases: :py:obj:`tuple`
 
-   A data structure to encapsulate a single kernel launch parameter.
+   Analogue to the :sycl_range:`sycl::range <>` class.
 
    The range is an abstraction that describes the number of elements
    in each dimension of buffers and index spaces. It can contain
@@ -225,7 +225,7 @@ Classes
 
 .. py:class:: NdRange(global_size, local_size)
 
-   A class to encapsulate all kernel launch parameters.
+   Analogue to the :sycl_ndrange:`sycl::nd_range <>` class.
 
    The NdRange defines the index space for a work group as well as
    the global index space. It is passed to parallel_for to execute
@@ -276,7 +276,7 @@ Classes
 
    Bases: :py:obj:`tuple`
 
-   A data structure to encapsulate a single kernel launch parameter.
+   Analogue to the :sycl_range:`sycl::range <>` class.
 
    The range is an abstraction that describes the number of elements
    in each dimension of buffers and index spaces. It can contain

dev/_sources/autoapi/numba_dpex/kernel_api/atomic_fence/index.rst.txt

@@ -22,28 +22,30 @@ Overview
    :class: summarytable
 
    * - :py:obj:`atomic_fence <numba_dpex.kernel_api.atomic_fence.atomic_fence>`\ (memory_order, memory_scope)
-     - The function for performing memory fence across all work-items.
+     - Performs a memory fence operations across all work-items.
 
 
 
 
 Functions
 ---------
-.. py:function:: atomic_fence(memory_order, memory_scope)
+.. py:function:: atomic_fence(memory_order: numba_dpex.kernel_api.memory_enums.MemoryOrder, memory_scope: numba_dpex.kernel_api.memory_enums.MemoryScope)
 
-   The function for performing memory fence across all work-items.
-   Modeled after ``sycl::atomic_fence`` function.
-   It provides control over re-ordering of memory load
-   and store operations. The ``atomic_fence`` function acts as a
-   fence across all work-items and devices specified by a
-   memory_scope argument.
+   Performs a memory fence operations across all work-items.
 
-   Args:
-   memory_order: The memory synchronization order.
+   The function is equivalent to the ``sycl::atomic_fence`` function and
+   controls the order of memory accesses (loads and stores) by individual
+   work-items.
 
-   memory_scope: The set of work-items and devices to which
-   the memory ordering constraints apply.
+   .. important::
+       The function is a no-op during CPython execution and only available in
+       JIT compiled mode of execution.
 
+   :param memory_order: The memory synchronization order.
+   :type memory_order: MemoryOrder
+   :param memory_scope: The set of work-items and devices to which
+                        the memory ordering constraints apply.
+   :type memory_scope: MemoryScope
 
 
 

dev/_sources/autoapi/numba_dpex/kernel_api/atomic_ref/index.rst.txt

@@ -22,7 +22,7 @@ Overview
    :class: summarytable
 
    * - :py:obj:`AtomicRef <numba_dpex.kernel_api.atomic_ref.AtomicRef>`
-     - Analogue to the ``sycl::atomic_ref`` class.
+     - Analogue to the :sycl_atomic_ref:`sycl::atomic_ref <>` class.
 
 
 
@@ -32,7 +32,7 @@ Classes
 
 .. py:class:: AtomicRef(ref, index, memory_order=MemoryOrder.RELAXED, memory_scope=MemoryScope.DEVICE, address_space=None)
 
-   Analogue to the ``sycl::atomic_ref`` class.
+   Analogue to the :sycl_atomic_ref:`sycl::atomic_ref <>` class.
 
    An atomic reference is a view into a data container that can be then updated
    atomically using any of the ``fetch_*`` member functions of the class.

dev/_sources/autoapi/numba_dpex/kernel_api/barrier/index.rst.txt

@@ -22,32 +22,41 @@ Overview
    :class: summarytable
 
    * - :py:obj:`group_barrier <numba_dpex.kernel_api.barrier.group_barrier>`\ (group, fence_scope)
-     - Performs a barrier operation across all work-items in a work group.
+     - Performs a barrier operation across all work-items in a work-group.
 
 
 
 
 Functions
 ---------
-.. py:function:: group_barrier(group: numba_dpex.kernel_api.index_space_ids.Group, fence_scope=MemoryScope.WORK_GROUP)
+.. py:function:: group_barrier(group: numba_dpex.kernel_api.index_space_ids.Group, fence_scope: numba_dpex.kernel_api.memory_enums.MemoryScope = MemoryScope.WORK_GROUP)
 
-   Performs a barrier operation across all work-items in a work group.
+   Performs a barrier operation across all work-items in a work-group.
 
-   The function is modeled after the ``sycl::group_barrier`` function. It
-   synchronizes work within a group of work items. All the work-items
+   The function is equivalent to the ``sycl::group_barrier`` function. It
+   synchronizes work within a group of work-items. All the work-items
    of the group must execute the barrier call before any work-item
    continues execution beyond the barrier.
 
-   The ``group_barrier`` performs mem-fence operations ensuring that memory
+   The ``group_barrier`` performs a memory fence operation ensuring that memory
    accesses issued before the barrier are not re-ordered with those issued
-   after the barrier: all work-items in group G execute a release fence prior
+   after the barrier. All work-items in group G execute a release fence prior
    to synchronizing at the barrier, all work-items in group G execute an
    acquire fence afterwards, and there is an implicit synchronization of these
    fences as if provided by an explicit atomic operation on an atomic object.
 
-   :param fence_scope: scope of any memory consistency
-   :type fence_scope: optional
-   :param operations that are performed by the barrier.:
+   .. important::
+       The function is not implemented yet for pure CPython execution and is
+       only supported in JIT compiled mode of execution.
+
+   :param group: Indicates the work-group inside which the barrier is to
+                 be executed.
+   :type group: Group
+   :param fence_scope: scope of any memory
+                       consistency operations that are performed by the barrier.
+   :type fence_scope: MemoryScope) (optional
+
+   :raises NotImplementedError: When the function is called directly from Python.