apply review comments

data-apis · kgryte · Nov 1, 2021 · Sep 13, 2021 · Sep 13, 2021 · Sep 14, 2021
commit d4b7a14dcd084fc16cabd93bee42369ed7fd014d
diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md
@@ -458,6 +458,8 @@ Exports the array for consumption by {ref}`function-from_dlpack` as a DLPack cap
 
         For other device types which do have a stream, queue or similar synchronization mechanism, the most appropriate type to use for `stream` is not yet determined. E.g., for SYCL one may want to use an object containing an in-order `cl::sycl::queue`. This is allowed when libraries agree on such a convention, and may be standardized in a future version of this API standard.
 
+        Support for any `stream` value other than `None` is optional and up to each library in question.
+
         Device-specific notes:
 
         :::{admonition} CUDA
@@ -1229,7 +1231,7 @@ Copy the array from the device it currently resides to the specified `device`.
 
 -   **stream**: _Optional\[ Union\[ int, Any ]]_
 
-    -   stream object to use during copy. In addition to the supported types as discussed in {ref}`method-__dlpack__`, any library-specific stream object is also allowed to be used here.
+    -   stream object to use during copy. In addition to the supported types as discussed in {ref}`method-__dlpack__`, any library-specific stream object is also allowed to be used here, with the caveat that using such an object would make the code non-portable.
 
 #### Returns
 
@@ -1238,6 +1240,5 @@ Copy the array from the device it currently resides to the specified `device`.
     -   an array with the same data and dtype, located on the specified `device`.
 
 ```{note}
-
-If `stream` is given, the copy operation will be enqueued on it; otherwise, it is enqueued on the default stream/queue (the concept of which is out of scope of this standard). Whether the copy is performed synchronously or asynchronously is up to the array library. As a result, if any synchronization (which is also out of scope of this standard) is required to guarantee data safety, the library should explain to its users.
+If `stream` is given, the copy operation will be enqueued on it; otherwise, it is enqueued on the default stream/queue. Whether the copy is performed synchronously or asynchronously is up to the array library. As a result, if any synchronization is required to guarantee data safety, the library should explain to its users.
 ```
diff --git a/spec/design_topics/device_support.md b/spec/design_topics/device_support.md
@@ -58,10 +58,10 @@ array API itself that can be instantiated to point to a specific physical or
 logical device. In other words, the standard does *not* include a universal
 `Device` object recognized by all compliant libraries.
 
-For array libraries that concern with multi-device support, including CPU and GPU,
-it is free to expose a library-specific device object for use (ex: creating an
-array on a particular device). For the purpose of this standard, it is considered
-an (important) implementation detail.
+For array libraries which concern themselves with multi-device support, including CPU and GPU,
+they are free to expose a library-specific device object for use (e.g., for creating an
+array on a particular device). It can be used as an input to `to_device`; the caveat
+is that it would make the code specific to that library.
 ```