Fix Buffer docs (#2176)

vulkano-rs · Apr 4, 2023 · 1f237a6 · 1f237a6
1 parent 096d3bc
commit 1f237a6
Show file tree

Hide file tree

Showing 2 changed files with 22 additions and 26 deletions.
diff --git a/vulkano/src/buffer/mod.rs b/vulkano/src/buffer/mod.rs
@@ -261,17 +261,14 @@ impl Buffer {
     /// Creates a new `Buffer` and writes `data` in it. Returns a [`Subbuffer`] spanning the whole
     /// buffer.
     ///
-    /// This only works with memory types that are host-visible. If you want to upload data to a
-    /// buffer allocated in device-local memory, you will need to create a staging buffer and copy
-    /// the contents over.
-    ///
-    /// > **Note**: You should **not** set the `buffer_info.size` field. The function does that
-    /// > itself.
+    /// > **Note**: This only works with memory types that are host-visible. If you want to upload
+    /// > data to a buffer allocated in device-local memory, you will need to create a staging
+    /// > buffer and copy the contents over.
     ///
     /// # Panics
     ///
-    /// - Panics if `T` has zero size.
-    /// - Panics if `T` has an alignment greater than `64`.
+    /// - Panics if `buffer_info.size` is not zero.
+    /// - Panics if the chosen memory type is not host-visible.
     pub fn from_data<T>(
         allocator: &(impl MemoryAllocator + ?Sized),
         buffer_info: BufferCreateInfo,
@@ -291,15 +288,14 @@ impl Buffer {
     /// Creates a new `Buffer` and writes all elements of `iter` in it. Returns a [`Subbuffer`]
     /// spanning the whole buffer.
     ///
-    /// This only works with memory types that are host-visible. If you want to upload data to a
-    /// buffer allocated in device-local memory, you will need to create a staging buffer and copy
-    /// the contents over.
-    ///
-    /// > **Note**: You should **not** set the `buffer_info.size` field. The function does that
-    /// > itself.
+    /// > **Note**: This only works with memory types that are host-visible. If you want to upload
+    /// > data to a buffer allocated in device-local memory, you will need to create a staging
+    /// > buffer and copy the contents over.
     ///
     /// # Panics
     ///
+    /// - Panics if `buffer_info.size` is not zero.
+    /// - Panics if the chosen memory type is not host-visible.
     /// - Panics if `iter` is empty.
     pub fn from_iter<T, I>(
         allocator: &(impl MemoryAllocator + ?Sized),
@@ -330,8 +326,9 @@ impl Buffer {
     /// Creates a new uninitialized `Buffer` for sized data. Returns a [`Subbuffer`] spanning the
     /// whole buffer.
     ///
-    /// > **Note**: You should **not** set the `buffer_info.size` field. The function does that
-    /// > itself.
+    /// # Panics
+    ///
+    /// - Panics if `buffer_info.size` is not zero.
     pub fn new_sized<T>(
         allocator: &(impl MemoryAllocator + ?Sized),
         buffer_info: BufferCreateInfo,
@@ -354,11 +351,9 @@ impl Buffer {
     /// Creates a new uninitialized `Buffer` for a slice. Returns a [`Subbuffer`] spanning the
     /// whole buffer.
     ///
-    /// > **Note**: You should **not** set the `buffer_info.size` field. The function does that
-    /// > itself.
-    ///
     /// # Panics
     ///
+    /// - Panics if `buffer_info.size` is not zero.
     /// - Panics if `len` is zero.
     pub fn new_slice<T>(
         allocator: &(impl MemoryAllocator + ?Sized),
@@ -375,11 +370,9 @@ impl Buffer {
     /// Creates a new uninitialized `Buffer` for unsized data. Returns a [`Subbuffer`] spanning the
     /// whole buffer.
     ///
-    /// > **Note**: You should **not** set the `buffer_info.size` field. The function does that
-    /// > itself.
-    ///
     /// # Panics
     ///
+    /// - Panics if `buffer_info.size` is not zero.
     /// - Panics if `len` is zero.
     pub fn new_unsized<T>(
         allocator: &(impl MemoryAllocator + ?Sized),
@@ -404,11 +397,9 @@ impl Buffer {
 
     /// Creates a new uninitialized `Buffer` with the given `layout`.
     ///
-    /// > **Note**: You should **not** set the `buffer_info.size` field. The function does that
-    /// > itself.
-    ///
     /// # Panics
     ///
+    /// - Panics if `buffer_info.size` is not zero.
     /// - Panics if `layout.alignment()` is greater than 64.
     pub fn new(
         allocator: &(impl MemoryAllocator + ?Sized),

diff --git a/vulkano/src/buffer/sys.rs b/vulkano/src/buffer/sys.rs
@@ -646,7 +646,12 @@ pub struct BufferCreateInfo {
 
     /// The size in bytes of the buffer.
     ///
-    /// The default value is `0`, which must be overridden.
+    /// When using the [`Buffer`] constructors, you must leave this at `0`. They fill this field
+    /// based on the data type of the contents and the other parameters you provide, and then pass
+    /// this create-info to [`RawBuffer::new`]. You must override the default when constructing
+    /// [`RawBuffer`] directly.
+    ///
+    /// The default value is `0`.
     pub size: DeviceSize,
 
     /// How the buffer is going to be used.