Document synchronization requirements on device_buffer copy ctors (#772)

Document caller synchronization expectations for copy constructors of `device_buffer`.

Fixes #766

Authors:
  - Mark Harris (https://github.com/harrism)

Approvers:
  - Rong Ou (https://github.com/rongou)
  - Jason Lowe (https://github.com/jlowe)
  - Conor Hoekstra (https://github.com/codereport)

URL: #772

include/rmm/device_buffer.hpp

@@ -103,8 +103,13 @@ class device_buffer {
   }
 
   /**
-   * @brief Construct a new device buffer by copying from a raw pointer to an
-   * existing host or device memory allocation.
+   * @brief Construct a new device buffer by copying from a raw pointer to an existing host or
+   * device memory allocation.
+   *
+   * @note This function does not synchronize `stream`. `source_data` is copied on `stream`, so the
+   * caller is responsible for correct synchronization to ensure that `source_data` is valid when
+   * the copy occurs. This includes destroying `source_data` in stream order after this function is
+   * called, or synchronizing or waiting on `stream` after this function returns as necessary.
    *
    * @throws rmm::bad_alloc If creating the new allocation fails.
    * @throws rmm::logic_error If `source_data` is null, and `size != 0`.
@@ -135,6 +140,11 @@ class device_buffer {
    *`other.size() != other.capacity()`, then the size and capacity of the newly
    * constructed `device_buffer` will be equal to `other.size()`.
    *
+   * @note This function does not synchronize `stream`. `other` is copied on `stream`, so the
+   * caller is responsible for correct synchronization to ensure that `other` is valid when
+   * the copy occurs. This includes destroying `other` in stream order after this function is
+   * called, or synchronizing or waiting on `stream` after this function returns as necessary.
+   *
    * @throws rmm::bad_alloc If creating the new allocation fails.
    * @throws rmm::cuda_error if copying from `other` fails.
    *