Merge pull request #1659 from bdmoore1/bdmoore1-api-reference-doc-review

oleksandr-pavlyk · web-flow · commit 0cb218154748 · 2024-05-03T21:24:34.000-05:00
diff --git a/docs/doc_sources/api_reference/dpctl/examples/usm_ndarray.rst b/docs/doc_sources/api_reference/dpctl/examples/usm_ndarray.rst
@@ -12,7 +12,7 @@
 .. rubric:: Use :meth:`usm_ndarray.device` to specify placement of new array
 
 .. code-block:: python
-    :caption: Create an USM-device empty array on the same device as another array
+    :caption: Create a USM-device empty array on the same device as another array
 
         from dpctl import tensor
 
diff --git a/docs/doc_sources/api_reference/dpctl/memory.rst b/docs/doc_sources/api_reference/dpctl/memory.rst
@@ -4,11 +4,11 @@
 :py:mod:`dpctl.memory`
 ======================
 
-Subpackage :py:mod:`dpctl.memory` exposes Unified Shared Memory(USM) operations.
+Subpackage :py:mod:`dpctl.memory` exposes Unified Shared Memory (USM) operations.
 
 Unified Shared Memory is a pointer-based memory management in SYCL guaranteeing that
 the host and all devices use a `unified address space <sycl_unified_address_space_>`_.
-Quoting from the SYCL specification:
+As described in the SYCL specification:
 
 .. _sycl_unified_address_space: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html#_unified_addressing
 
diff --git a/docs/doc_sources/api_reference/dpctl/program.rst b/docs/doc_sources/api_reference/dpctl/program.rst
@@ -4,7 +4,7 @@
 =======================
 
 :py:mod:`dpctl.program` provides a way to create a SYCL kernel
-from either an OpenCL program source code represented as a string
+from either an OpenCL* program source code represented as a string
 or a SPIR-V binary file.
 
 It implements creation of interoperability
diff --git a/docs/doc_sources/api_reference/dpctl/sycl_usm_array_interface.rst b/docs/doc_sources/api_reference/dpctl/sycl_usm_array_interface.rst
@@ -6,7 +6,7 @@
 Python objects representing USM allocations, such as :py:class:`dpctl.memory.MemoryUSMDevice`,
 :py:class:`dpctl.memory.MemoryUSMShared`, :py:class:`dpctl.memory.MemoryUSMHost`,
 or :py:class:`dpctl.tensor.usm_ndarray`, distinguish themselves from other Python objects
-by providing ``__sycl_usm_array_interface__`` attribute describing the allocation in a
+by providing the ``__sycl_usm_array_interface__`` attribute describing the allocation in a
 Python dictionary with the following fields:
 
 ``"shape"``
@@ -32,23 +32,22 @@ Python dictionary with the following fields:
     is read-only).
 
 ``"strides"``
-    an optional tuple of integers describing number of array elements needed to jump
+    An optional tuple of integers describing number of array elements needed to jump
     to the next array element in the corresponding dimensions. The default value of ``None``
     implies a C-style contiguous (row-major compact) layout of the array.
 
 ``"offset"``
-    an optional Python integer encoding offset in number of elements from the pointer
+    An optional Python integer encoding offset in number of elements from the pointer
     provided in ``"data"`` field to the array element with zero indices. Default: `0`.
 
 ``"syclobj"``
     Python object from which SYCL context to which represented USM allocation is bound.
 
     ==============================================  =======================================
-    Filter selector string                          Platform's default context for platform
-                                                    the SYCL device selected by the
-                                                    :ref:`filter selector string <filter_selector_string>`
-                                                    is a part of.
-    :py:class:`dpctl.SyclContext`                   An explicitly provided context
+    Filter selector string                          The default context of the platform
+                                                    selected by
+                                                    :ref:`filter selector string <filter_selector_string>`.
+    :py:class:`dpctl.SyclContext`                   An explicitly provided context.
     Python capsule with name ``"SyclContextRef"``   A Python capsule carrying a
                                                     ``DPCTLSyclContextRef`` opaque pointer.
     :py:class:`dpctl.SyclQueue`                     An explicitly provided queue which
@@ -61,7 +60,7 @@ Python dictionary with the following fields:
     ==============================================  =======================================
 
 ``"version"``
-    version of the interface. At present, the only supported value is `1`.
+    Version of the interface. At present, the only supported value is `1`.
 
 
 .. _numpy_array_interface: https://numpy.org/doc/stable/reference/arrays.interface.html
diff --git a/docs/doc_sources/api_reference/dpctl/tensor.data_type_functions.rst b/docs/doc_sources/api_reference/dpctl/tensor.data_type_functions.rst
@@ -3,7 +3,7 @@
 Data type functions
 ===================
 
-Package :py:mod:`dpctl.tensor` contains the following data type functions conforming
+The package :py:mod:`dpctl.tensor` contains the following data type functions conforming
 to `Python Array API specification <array_api_data_type_fns_>`_:
 
 .. _array_api_data_type_fns: https://data-apis.org/array-api/latest/API_specification/data_type_functions.html
diff --git a/docs/doc_sources/api_reference/dpctl/tensor.data_types.rst b/docs/doc_sources/api_reference/dpctl/tensor.data_types.rst
@@ -28,11 +28,11 @@ Data types
 +----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | ``uint64``     | A 64-bit unsigned integer type capable of representing :math:`v` subject to :math:`0 \le v < 2^{64}`                                                                                    |
 +----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ``float16``    | An IEEE-754 half-precision (16-bits) binary floating-point number (see `IEEE 754-2019`_)                                                                                                |
+| ``float16``    | An IEEE-754 half-precision (16-bit) binary floating-point number (see `IEEE 754-2019`_)                                                                                                 |
 +----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ``float32``    | An IEEE-754 single-precision (32-bits) binary floating-point number (see `IEEE 754-2019`_)                                                                                              |
+| ``float32``    | An IEEE-754 single-precision (32-bit) binary floating-point number (see `IEEE 754-2019`_)                                                                                               |
 +----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ``float64``    | An IEEE-754 double-precision (64-bits) binary floating-point number (see `IEEE 754-2019`_)                                                                                              |
+| ``float64``    | An IEEE-754 double-precision (64-bit) binary floating-point number (see `IEEE 754-2019`_)                                                                                               |
 +----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | ``complex64``  | Single-precision (64-bit) complex floating-point number whose real and imaginary components are IEEE 754 single-precision (32-bit) binary floating-point numbers (see `IEEE 754-2019`_) |
 +----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -48,7 +48,7 @@ Half-precision floating-point type ``float16`` is supported only for devices who
 Double-precision floating-point type ``float64`` and double-precision complex floating-point type ``complex128`` are supported only for devices whose attribute :attr:`dpctl.SyclDevice.has_aspect_fp64`
 evaluates to ``True``.
 
-Requests to create an instance of array object for these types on devices where these prerequisites are not met will raise an exception.
+If prerequisites are not met, requests to create an instance of an array object for these types will raise an exception.
 
 .. TODO: provide a note on support for sub-normal numbers
 
@@ -118,7 +118,7 @@ Type promotion rules govern the behavior of an array library when a function doe
 a dedicated implementation for the data type(s) of the input array(s).
 
 In such a case, input arrays may be cast to data types for which a dedicated implementation
-exists. e.g., when :data:`sin` is applied to array of integral values.
+exists. For example, when :data:`sin` is applied to array of integral values.
 
 Type promotion rules used in :py:mod:`dpctl.tensor` are consistent with the
 Python Array API specification's `type promotion rules <https://data-apis.org/array-api/latest/API_specification/type_promotion.html>`_
diff --git a/docs/doc_sources/api_reference/dpctl/tensor.inspection.rst b/docs/doc_sources/api_reference/dpctl/tensor.inspection.rst
@@ -5,7 +5,7 @@ Inspection API
 
 
 :mod:`dpctl.tensor` implements a way to introspect implementation- and device-
-capabilities of array library as specified in
+capabilities of an array library as specified in
 `Python Array API standard <array_api_inspection>`_:
 
 .. currentmodule:: dpctl.tensor
diff --git a/docs/doc_sources/api_reference/dpctl/tensor.rst b/docs/doc_sources/api_reference/dpctl/tensor.rst
@@ -7,7 +7,7 @@
 
 .. currentmodule:: dpctl.tensor
 
-:py:mod:`dpctl.tensor` provides a reference implementation of
+:py:mod:`dpctl.tensor` provides a reference implementation of the
 :array_api:`Python Array API <>` specification. The implementation
 uses :ref:`data-parallel <parallelism_definitions>` algorithms suitable for execution on accelerators,
 such as GPUs.
diff --git a/docs/doc_sources/api_reference/dpctl_capi.rst b/docs/doc_sources/api_reference/dpctl_capi.rst
@@ -1,6 +1,6 @@
 .. _dpctl_capi:
 
-:py:mod:`dpctl` C-API
+:py:mod:`dpctl` C API
 =====================
 
 :py:mod:`dpctl` core classes are implemented in Cython. C declarations for Python objects
@@ -41,7 +41,7 @@ Exported typedefs
 
 .. c:struct:: PySyclProgramType
 
-In order to check whether a particular Python objct is an instance of :py:class:`dpctl.SyclQueue` one would write:
+To check whether a particular Python object is an instance of :py:class:`dpctl.SyclQueue`:
 
 .. code-block:: C
     :caption: Check if an object is of type :c:struct:`PySyclQueueType`
@@ -123,7 +123,7 @@ API for :c:struct:`Py_MemoryObject`
 .. c:function:: DPCTLSyclUSMRef Memory_GetUsmPointer(struct Py_MemoryObject *o)
 
     :param o: Input object
-    :returns: Opaque pointer to USM allocation represented by Python object
+    :returns: Opaque pointer to USM allocation represented by Python object.
 
 .. c:function:: DPCTLSyclContextRef Memory_GetSyclContext(struct Py_MemoryObject *o)
 
@@ -172,24 +172,24 @@ API for :c:struct:`PyUSMArrayObject`
 .. c:function:: Py_ssize_t * UsmNDArray_GetShape(struct PyUSMArrayObject *arr)
 
     :param arr: Input object
-    :returns: Pointer to array of sizes of array along each dimension
+    :returns: Pointer to array of sizes of array along each dimension.
 
     The array has at least as many elements as returned by :c:func:`UsmNDArray_GetNDim`
     applied to input object ``arr``.
 
 .. c:function:: Py_ssize_t * UsmNDArray_GetStrides(struct PyUSMArrayObject *arr)
 
     :param arr: Input object
-    :returns: Pointer to array of strides of array along each dimension
-    :returns: NULL if array is C- or F-contiguous
+    :returns: Pointer to array of strides of array along each dimension.
+    :returns: NULL if array is C- or F-contiguous.
 
     The array has at least as many elements as returned by :c:func:`UsmNDArray_GetNDim`
     applied to input object ``arr``.
 
 .. c:function:: int UsmNDarray_GetTypenum(struct PyUSMArrayObject *arr)
 
     :param arr: Input object
-    :returns: An integer encoding the type of array elements
+    :returns: An integer encoding the type of array elements.
 
     The encoding is consistent with that integral values corresponding to enums
     used by :py:mod:`numpy`. See `NumPy Dtype C-API <https://numpy.org/doc/stable/reference/c-api/dtype.html#enumerated-types>`_.
@@ -202,7 +202,7 @@ API for :c:struct:`PyUSMArrayObject`
 .. c:function:: int UsmNDarray_GetFlags(struct PyUSMArrayObject *arr)
 
     :param arr: Input object
-    :returns: An integer encoding flags attribute of the array
+    :returns: An integer encoding flags attribute of the array.
 
     The flag encodes whether the array is C-contiguous, F-contiguous,
     whether it is read-only, or can be modified.
@@ -219,12 +219,12 @@ API for :c:struct:`PyUSMArrayObject`
 
     :param arr: Input object
     :returns: Offset of zero multi-index array element from the beginning of
-              the USM allocation
+              the USM allocation.
 
 .. c:function:: void UsmNDArray_SetWritableFlag(struct PyUSMArrayObject *arr, int flag)
 
     :param arr: Input object
-    :param flags: Whether to set writable flag of the array to read-only, or to writable
+    :param flags: Whether to set writable flag of the array to read-only, or to writable.
 
     Non-zero value of ``flag`` parameter sets the array flag bit to writable, a zero-value
     of ``flag`` parameter sets the flag bit of the array to read-only.
diff --git a/docs/doc_sources/api_reference/dpctl_cmake.rst b/docs/doc_sources/api_reference/dpctl_cmake.rst
@@ -3,10 +3,10 @@
 CMake support
 =============
 
-:py:mod:`dpctl` comes with configuration file `dpctl-config.cmake` which is installed
+:py:mod:`dpctl` comes with the configuration file `dpctl-config.cmake` which is installed
 on the `standard search path CMake uses to search for packages <cmake_find_package_search_paths_>`_.
 
-To build your extension that leverages :py:mod:`dpctl` include the following line in your cmake script:
+To build your extension that leverages :py:mod:`dpctl`, include the following line in your CMake script:
 
 .. code-block:: cmake
 
diff --git a/docs/doc_sources/api_reference/dpctl_cython.rst b/docs/doc_sources/api_reference/dpctl_cython.rst
@@ -38,5 +38,5 @@ File ``_backend.pxd`` redefines symbols from :ref:`DPCTLSyclInterface library <l
 
 File ``sycl.pxd`` provides casters from opaque types in "DPCTLSyclInterface" C library to SYCL C++ object pointers.
 
-Please refer to `examples/cython <https://github.com/IntelPython/dpctl/blob/master/examples/cython>`_ folder in the project
+Please refer to the `examples/cython <https://github.com/IntelPython/dpctl/blob/master/examples/cython>`_ folder in the project
 repository for a collection of examples.
diff --git a/docs/doc_sources/api_reference/dpctl_pybind11.rst b/docs/doc_sources/api_reference/dpctl_pybind11.rst
@@ -3,7 +3,7 @@
 pybind11 API
 ============
 
-:py:mod:`dpctl` builds on top of :ref:`C-API <dpctl_capi>` to integrate with
+:py:mod:`dpctl` builds on top of :ref:`C API <dpctl_capi>` to integrate with the
 `pybind11 <pybind11_url>`_ Python extension generator.
 
 .. code-block:: c++
@@ -23,7 +23,7 @@ pybind11 API
         m.def("get_device_name", &get_device_name);
     }
 
-The extension should be compiled using Intel(R) oneAPI DPC++ compiler:
+The extension should be compiled using the Intel(R) oneAPI DPC++ compiler:
 
 .. code-block:: bash
 
diff --git a/docs/doc_sources/api_reference/index.rst b/docs/doc_sources/api_reference/index.rst
@@ -13,7 +13,7 @@ The package ``dpctl`` provides
    - :ref:`API objects <dpctl_utils_pyapi>` in :py:mod:`dpctl.utils` namespace
 * SYCL-based Python array library
    - :ref:`API objects <dpctl_tensor_pyapi>` in :py:mod:`dpctl.tensor` namespace
-* Python C-API
+* Python C API
    - :ref:`C API <dpctl_capi>` for working with Python classes defined in :mod:`dpctl`
 * Extension generators
    - :ref:`Declarations <dpctl_cython_api>` for classes defined in :py:mod:`dpctl` and supporting functions for use in `Cython <cython_docs_>`_.
diff --git a/docs/doc_sources/api_reference/libsyclinterface/index.rst b/docs/doc_sources/api_reference/libsyclinterface/index.rst
@@ -1,11 +1,11 @@
 .. _libsyclinterface:
 
 C Library SyclInterface
-=======================
+========================
 
-:py:mod:`dpctl` contains SyclInterface library that provides C API to a subset of functionality exposed in DPC++ runtime classes.
+:py:mod:`dpctl` contains the SyclInterface library which provides C APIs to a subset of functionality exposed in DPC++ runtime classes.
 
-The C-API was necessary to support :py:mod:`numba_dpex` project to use DPC++ runtime classes from LLVM it generates.
+The C API was necessary to support the :py:mod:`numba_dpex` project to use DPC++ runtime classes from LLVM it generates.
 
 Full :doc:`API reference <generated/index>` is generated using doxyrest from doxygen strings.
 
