Expand documentation of Queue::write_texture. (#3173)

wgpu/src/lib.rs

@@ -3596,13 +3596,23 @@ impl Queue {
         }
     }
 
-    /// Schedule a data write into `texture`.
+    /// Schedule a write of some data into a texture.
+    ///
+    /// * `data` contains the texels to be written, which must be in
+    ///   [the same format as the texture](TextureFormat).
+    /// * `data_layout` describes the memory layout of `data`, which does not necessarily
+    ///   have to have tightly packed rows.
+    /// * `texture` specifies the texture to write into, and the location within the
+    ///   texture (coordinate offset, mip level) that will be overwritten.
+    /// * `size` is the size, in texels, of the region to be written.
     ///
     /// This method is intended to have low performance costs.
     /// As such, the write is not immediately submitted, and instead enqueued
     /// internally to happen at the start of the next `submit()` call.
+    /// However, `data` will be immediately copied into staging memory; so the caller may
+    /// discard it any time after this call completes.
     ///
-    /// This method fails if `data` overruns the size of fragment of `texture` specified with `size`.
+    /// This method fails if `size` overruns the size of `texture`, or if `data` is too short.
     pub fn write_texture(
         &self,
         texture: ImageCopyTexture,
@@ -3613,7 +3623,7 @@ impl Queue {
         Context::queue_write_texture(&*self.context, &self.id, texture, data, data_layout, size)
     }
 
-    /// Schedule a copy of data from `image` into `texture`
+    /// Schedule a copy of data from `image` into `texture`.
     #[cfg(all(target_arch = "wasm32", not(feature = "webgl")))]
     pub fn copy_external_image_to_texture(
         &self,