Raphael detailed wording suggestions

source/elements/oneMKL/source/domains/dft/config_params/workspace_placement.rst

@@ -9,15 +9,17 @@ Workspace placement
 
 DFT implementations often require temporary storage for intermediate data whilst computing DFTs.
 This temporary storage is referred to as a *workspace*.
-Whilst this is managed automatically by default (``config_param::WORKSPACE_AUTOMATIC``), 
-it may be preferable to provide an external workspace (``config_param::WORKSPACE_EXTERNAL``) for the following reasons:
+Whilst this is managed automatically by default (``config_value::WORKSPACE_AUTOMATIC`` 
+set for ``config_param::WORKSPACE_PLACEMENT``), it may be preferable to provide an external 
+workspace (``config_value::WORKSPACE_EXTERNAL`` set for ``config_param::WORKSPACE_PLACEMENT``) 
+for the following reasons:
 
-* To reduce the number of GPU mallocs / frees
-* To reduce memory consumption
+* to reduce the number of GPU mallocs / frees;
+* to reduce memory consumption.
 
-For some backends and configurations, ``config_param::WORKSPACE_EXTERNAL`` may reduce performance.
+For some backends and configurations, ``config_value::WORKSPACE_EXTERNAL`` may reduce performance.
 
-A typical workflow for using ``config_param::WORKSPACE_EXTERNAL`` is given in the section :ref:`onemkl_dft_typical_usage_of_workspace_external`.
+A typical workflow for using ``config_value::WORKSPACE_EXTERNAL`` is given in the section :ref:`onemkl_dft_typical_usage_of_workspace_external`.
 
 WORKSPACE_PLACEMENT
 +++++++++++++++++++
@@ -43,18 +45,19 @@ When set to ``config_value::WORKSPACE_AUTOMATIC`` the user does not need to prov
 The configuration ``config_param::WORKSPACE_PLACEMENT`` can be set to 
 ``config_value::WORKSPACE_EXTERNAL`` to allow the workspace to be set manually. 
 
-When a descriptor is committed with ``config_value::WORKSPACE_EXTERNAL`` set, 
-the user must provide an external workspace. 
+When a descriptor is committed with ``config_value::WORKSPACE_EXTERNAL`` set 
+for ``config_param::WORKSPACE_PLACEMENT``, the user must provide an external 
+workspace before calling any compute function.
 See :ref:`onemkl_dft_descriptor_set_workspace` and :ref:`onemkl_dft_typical_usage_of_workspace_external`.
 
 .. _onemkl_dft_typical_usage_of_workspace_external:
 
 Typical usage of ``WORKSPACE_EXTERNAL``
 +++++++++++++++++++++++++++++++++++++++
 
-Usage of ``WORKSPACE_EXTERNAL`` typically involves the following order of operations:
+Usage of ``config_value::WORKSPACE_EXTERNAL`` typically involves the following order of operations:
 
-#. ``WORKSPACE_EXTERNAL`` is set for the uncommitted descriptor.
+#. ``config_value::WORKSPACE_EXTERNAL`` is set for the uncommitted descriptor.
 #. The descriptor is committed.
 #. The required workspace size is queried.
 #. A workspace of sufficient size is provided to the descriptor.

source/elements/oneMKL/source/domains/dft/descriptor.rst

@@ -427,7 +427,7 @@ type ``oneapi::mkl::dft::domain``, ``oneapi::mkl::dft::precision``,
 set_workspace
 +++++++++++++
 
-Set the workspace for when ``config_param::WORKSPACE_PLACEMENT`` is set to ``config_value::WORKSPACE_EXTERNAL``.
+Sets the workspace for when ``config_param::WORKSPACE_PLACEMENT`` is set to ``config_value::WORKSPACE_EXTERNAL``.
 
 .. rubric:: Description
 
@@ -437,8 +437,9 @@ This function may only be called after the descriptor has been committed.
 The size of the provided workspace must be equal to or larger than the required 
 workspace size obtained by calling ``descriptor<prec, dom>::get_value(config_param::WORKSPACE_EXTERNAL_BYTES, &workspaceBytes)``.
 
-A descriptor where ``WORKSPACE_EXTERNAL`` is specified is not a valid descriptor 
-for compute calls until this function has been successfully called.
+A descriptor where ``config_value::WORKSPACE_EXTERNAL`` is specified for 
+``config_param::WORKSPACE_PLACEMENT`` is not a valid descriptor for compute 
+calls until this function has been successfully called.
 
 The type of workspace must match the compute calls for which it is used.
 That is, if the workspace is provided as a ``sycl::buffer``, the compute
@@ -479,10 +480,10 @@ be used in compute calls. However, the aforementioned restrictions will still ap
    .. rubric:: Input Parameters
 
    workspaceBuf
-      A workspace buffer where ``scalar_type`` is the floating point type according to ``prec``. This buffer must be sufficiently large or an exception will be thrown.
+      A workspace buffer where ``scalar_type`` is the floating-point type according to ``prec``. This buffer must be sufficiently large or an exception will be thrown.
 
    workspaceUSM
-      A workspace USM allocation where ``scalar_type`` is the floating point type according to ``prec``. This allocation must be accessible on the device on which the descriptor is committed. It is assumed that this USM allocation is sufficiently large. The pointer is expected to be aligned to ``scalar_type``.
+      A workspace USM allocation where ``scalar_type`` is the floating-point type according to ``prec``. This allocation must be accessible on the device on which the descriptor is committed. It is assumed that this USM allocation is sufficiently large. The pointer is expected to be aligned to ``scalar_type``.
 
 .. container:: section