From 0360accc8c91f8d6364187307c4f6f9092213d70 Mon Sep 17 00:00:00 2001
From: Rua <ruawhitepaw@gmail.com>
Date: Sun, 9 Oct 2022 14:08:48 +0200
Subject: [PATCH] #2030 doc fixes

---
 vulkano/src/buffer/device_local.rs | 29 ++++++++++++++++-------------
 vulkano/src/image/immutable.rs     | 12 ++++++++++++
 2 files changed, 28 insertions(+), 13 deletions(-)

diff --git a/vulkano/src/buffer/device_local.rs b/vulkano/src/buffer/device_local.rs
index db690af6ca..c47dc383d9 100644
--- a/vulkano/src/buffer/device_local.rs
+++ b/vulkano/src/buffer/device_local.rs
@@ -177,10 +177,12 @@ where
 {
     /// Builds a `DeviceLocalBuffer` that copies its data from another buffer.
     ///
-    /// This function returns two objects: the newly-created buffer, and a future representing
-    /// the initial upload operation. In order to be allowed to use the `DeviceLocalBuffer`, you
-    /// must either submit your operation after this future, or execute this future and wait for it
-    /// to be finished before submitting your own operation.
+    /// This is a convenience function, equivalent to calling [`new`](DeviceLocalBuffer::new) with
+    /// the queue family index of `command_buffer_builder`, then recording a `copy_buffer` command
+    /// to `command_buffer_builder`.
+    ///
+    /// `command_buffer_builder` can then be used to record other commands, built, and executed as
+    /// normal. If it is not executed, the buffer contents will be left undefined.
     ///
     /// # Panics
     ///
@@ -226,16 +228,11 @@ impl<T> DeviceLocalBuffer<T>
 where
     T: BufferContents,
 {
-    /// Builds an `DeviceLocalBuffer` from some data.
-    ///
-    /// This function builds a memory-mapped intermediate buffer, writes the data to it, builds a
-    /// command buffer that copies from this intermediate buffer to the final buffer, and finally
-    /// submits the command buffer as a future.
+    /// Builds a `DeviceLocalBuffer` from some data.
     ///
-    /// This function returns two objects: the newly-created buffer, and a future representing
-    /// the initial upload operation. In order to be allowed to use the `DeviceLocalBuffer`, you
-    /// must either submit your operation after this future, or execute this future and wait for it
-    /// to be finished before submitting your own operation.
+    /// This is a convenience function, equivalent to creating a `CpuAccessibleBuffer`, writing
+    /// `data` to it, then calling [`from_buffer`](DeviceLocalBuffer::from_buffer) to copy the data
+    /// over.
     ///
     /// # Panics
     ///
@@ -267,6 +264,12 @@ impl<T> DeviceLocalBuffer<[T]>
 where
     [T]: BufferContents,
 {
+    /// Builds a `DeviceLocalBuffer` from an iterator of data.
+    ///
+    /// This is a convenience function, equivalent to creating a `CpuAccessibleBuffer`, writing
+    /// `iter` to it, then calling [`from_buffer`](DeviceLocalBuffer::from_buffer) to copy the data
+    /// over.
+    ///
     /// # Panics
     ///
     /// - Panics if `T` has zero size.
diff --git a/vulkano/src/image/immutable.rs b/vulkano/src/image/immutable.rs
index 58b0c53874..f9cd3b805f 100644
--- a/vulkano/src/image/immutable.rs
+++ b/vulkano/src/image/immutable.rs
@@ -176,6 +176,10 @@ impl ImmutableImage {
     }
 
     /// Construct an ImmutableImage from the contents of `iter`.
+    ///
+    /// This is a convenience function, equivalent to creating a `CpuAccessibleBuffer`, writing
+    /// `iter` to it, then calling [`from_buffer`](ImmutableImage::from_buffer) to copy the data
+    /// over.
     pub fn from_iter<Px, I, L, A>(
         iter: I,
         dimensions: ImageDimensions,
@@ -208,6 +212,14 @@ impl ImmutableImage {
     }
 
     /// Construct an ImmutableImage containing a copy of the data in `source`.
+    ///
+    /// This is a convenience function, equivalent to calling
+    /// [`uninitialized`](ImmutableImage::uninitialized) with the queue family index of
+    /// `command_buffer_builder`, then recording a `copy_buffer_to_image` command to
+    /// `command_buffer_builder`.
+    ///
+    /// `command_buffer_builder` can then be used to record other commands, built, and executed as
+    /// normal. If it is not executed, the image contents will be left undefined.
     pub fn from_buffer<L, A>(
         source: Arc<dyn BufferAccess>,
         dimensions: ImageDimensions,