[KHRGA-84] Updated EP nd_range classes

source/conf.py

@@ -212,6 +212,9 @@ def make_ref(ref_str, ref_view, ref_sufix):
         "Section 4.7.5",
         "#_parallel_for_hierarchical_invoke",
     )
+    + make_ref(
+        "SYCL_SPEC_ND_RANGE", "Section 4.9.1.2", "#subsubsec:nd-range-class"
+    )
     + f"""
 .. _`SYCL Specification`: {sycl_ref_url}
 .. |true| replace:: ``true``
@@ -236,7 +239,6 @@ def make_ref(ref_str, ref_view, ref_sufix):
 .. |SYCL_SPEC_ITEM| replace:: `SYCL Specification`_ Section 4.10.1.4
 .. |SYCL_SPEC_H_ITEM| replace:: `SYCL Specification`_ Section 4.10.1.6
 .. |SYCL_SPEC_ND_ITEM| replace:: `SYCL Specification`_ Section 4.10.1.5
-.. |SYCL_SPEC_ND_RANGE| replace:: `SYCL Specification`_ Section 4.10.1.2
 .. |SYCL_SPEC_DEVICE_EVENT| replace:: `SYCL Specification`_ Section 4.7.8
 .. |SYCL_SPEC_HANDLER| replace:: `SYCL Specification`_ Section 4.10.4
 .. |SYCL_SPEC_KERNEL| replace:: `SYCL Specification`_ Section 4.12

source/iface/nd_range.rst

@@ -2,70 +2,81 @@
   Copyright 2020 The Khronos Group Inc.
   SPDX-License-Identifier: CC-BY-4.0
 
-.. rst-class:: api-class
-
 .. _nd_range:
 
-
-==================
+******************
 ``sycl::nd_range``
-==================
+******************
 
 ::
 
-   template <int dimensions = 1>
-   class nd_range;
-
-
-The ``nd_range`` defines the index space for a work group as well as
-the global index space. It is passed to :ref:`handler-parallel_for` to
-execute a kernel on a set of work items.
-
+  template <int Dimensions = 1>
+  class nd_range;
 
 .. rubric:: Template parameters
 
 ================  ===
-``dimensions``    Number of dimensions
+``Dimensions``    Number of dimensions in the ``sycl::nd_range``.
 ================  ===
 
+The ``sycl::nd_range`` class defines the iteration domain of both
+the work-groups and the overall dispatch.
+
+A ``sycl::nd_range`` comprises two
+:ref:`range` parameters: the whole range over which
+the kernel is to be executed, and the range of each work group.
+
+The ``sycl::nd_range`` class template provides the :ref:`common-byval`.
 
 .. seealso:: |SYCL_SPEC_ND_RANGE|
 
+==============
 (constructors)
 ==============
 
 ::
 
-  nd_range(sycl::range<dimensions> globalSize, sycl::range<dimensions> localSize,
-           sycl::id<dimensions> offset = sycl::id<dimensions>());
+  nd_range<Dimensions>(
+      sycl::range<Dimensions> globalSize,
+      sycl::range<Dimensions> localSize,
+      sycl::id<Dimensions> offset = sycl::id<Dimensions>());
+
+Construct an ``sycl::nd_range`` from the local
+and global constituent :ref:`range`.
 
-Construct an ``nd_range``.
+Supplying the option offset is deprecated in SYCL 2020.
+If the offset is not provided it will default to no offset.
 
 .. rubric:: Parameters
 
 ==================  ===
-``globalSize``      dimensions of the entire index space
-``localSize``       dimensions of the work group
-``offset``          Origin of the index space [deprecated in SYCL 2020]
+``globalSize``      Dimensions of the entire index space.
+``localSize``       Dimensions of the work group.
+``offset``          Origin of the index space. [deprecated in SYCL 2020]
 ==================  ===
 
+
+================
+Member functions
+================
+
 ``get_global_range``
 ====================
 
 ::
 
-  sycl::range<dimensions> get_global_range() const;
+  sycl::range<Dimensions> get_global_range() const;
 
-Returns a :ref:`range` defining the index space.
+Return the constituent global :ref:`range`.
 
 ``get_local_range``
 ===================
 
 ::
 
-  sycl::range<dimensions> get_local_range() const;
+  sycl::range<Dimensions> get_local_range() const;
 
-Returns a :ref:`range` defining the index space of a work group.
+Return the constituent local :ref:`range`.
 
 ``get_group_range``
 ===================
@@ -74,14 +85,20 @@ Returns a :ref:`range` defining the index space of a work group.
 
   sycl::range<dimensions> get_group_range() const;
 
-Returns a :ref:`range` defining the number of work groups in every dimension.
+Returns a :ref:`range` representing the number of
+groups in each dimension.
+
+This range would result from ``globalSize``/``localSize``
+as provided on construction.
 
 
 ``get_offset``
 ==============
 
 ::
 
-  sycl::id<dimensions> get_offset() const;
+  sycl::id<Dimensions> get_offset() const;
+
+Deprecated in SYCL 2020.
 
 Returns a :ref:`id` defining the offset.