Link _len() functions to their array-getter using intradoc-links (#490)

Point the user in the right direction telling them where to get the
length of the mutable slice that has to passed in, and document that
these have to be default-initialized (so that `s_type` is set
appropriately) and `p_next` can optionally be set too.

ash/src/device.rs

@@ -297,6 +297,7 @@ impl Device {
             .get_buffer_memory_requirements2(self.handle(), info, out);
     }
 
+    /// Retrieve the number of elements to pass to [`Self::get_image_sparse_memory_requirements2()`]
     pub unsafe fn get_image_sparse_memory_requirements2_len(
         &self,
         info: &vk::ImageSparseMemoryRequirementsInfo2,
@@ -312,6 +313,9 @@ impl Device {
     }
 
     #[doc = "<https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/vkGetImageSparseMemoryRequirements2.html>"]
+    ///
+    /// Call [`Self::get_image_sparse_memory_requirements2_len()`] to query the number of elements to pass to `out`.
+    /// Be sure to [`Default::default()`]-initialize these elements and optionally set their `p_next` pointer.
     pub unsafe fn get_image_sparse_memory_requirements2(
         &self,
         info: &vk::ImageSparseMemoryRequirementsInfo2,

ash/src/extensions/khr/get_memory_requirements2.rs

@@ -45,6 +45,7 @@ impl GetMemoryRequirements2 {
             .get_image_memory_requirements2_khr(self.handle, info, memory_requirements);
     }
 
+    /// Retrieve the number of elements to pass to [`Self::get_image_sparse_memory_requirements2()`]
     pub unsafe fn get_image_sparse_memory_requirements2_len(
         &self,
         info: &vk::ImageSparseMemoryRequirementsInfo2KHR,
@@ -61,18 +62,21 @@ impl GetMemoryRequirements2 {
     }
 
     #[doc = "<https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/vkGetImageSparseMemoryRequirements2KHR.html>"]
+    ///
+    /// Call [`Self::get_image_sparse_memory_requirements2_len()`] to query the number of elements to pass to `out`.
+    /// Be sure to [`Default::default()`]-initialize these elements and optionally set their `p_next` pointer.
     pub unsafe fn get_image_sparse_memory_requirements2(
         &self,
         info: &vk::ImageSparseMemoryRequirementsInfo2KHR,
-        sparse_memory_requirements: &mut [vk::SparseImageMemoryRequirements2KHR],
+        out: &mut [vk::SparseImageMemoryRequirements2KHR],
     ) {
-        let mut count = sparse_memory_requirements.len() as u32;
+        let mut count = out.len() as u32;
         self.get_memory_requirements2_fn
             .get_image_sparse_memory_requirements2_khr(
                 self.handle,
                 info,
                 &mut count,
-                sparse_memory_requirements.as_mut_ptr(),
+                out.as_mut_ptr(),
             );
     }
 

ash/src/extensions/khr/get_physical_device_properties2.rs

@@ -84,6 +84,7 @@ impl GetPhysicalDeviceProperties2 {
             .get_physical_device_properties2_khr(physical_device, properties);
     }
 
+    /// Retrieve the number of elements to pass to [`Self::get_physical_device_queue_family_properties2()`]
     pub unsafe fn get_physical_device_queue_family_properties2_len(
         &self,
         physical_device: vk::PhysicalDevice,
@@ -99,20 +100,24 @@ impl GetPhysicalDeviceProperties2 {
     }
 
     #[doc = "<https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/vkGetPhysicalDeviceQueueFamilyProperties2KHR.html>"]
+    ///
+    /// Call [`Self::get_physical_device_queue_family_properties2_len()`] to query the number of elements to pass to `out`.
+    /// Be sure to [`Default::default()`]-initialize these elements and optionally set their `p_next` pointer.
     pub unsafe fn get_physical_device_queue_family_properties2(
         &self,
         physical_device: vk::PhysicalDevice,
-        queue_family_properties: &mut [vk::QueueFamilyProperties2KHR],
+        out: &mut [vk::QueueFamilyProperties2KHR],
     ) {
-        let mut count = queue_family_properties.len() as u32;
+        let mut count = out.len() as u32;
         self.get_physical_device_properties2_fn
             .get_physical_device_queue_family_properties2_khr(
                 physical_device,
                 &mut count,
-                queue_family_properties.as_mut_ptr(),
+                out.as_mut_ptr(),
             );
     }
 
+    /// Retrieve the number of elements to pass to [`Self::get_physical_device_sparse_image_format_properties2()`]
     pub unsafe fn get_physical_device_sparse_image_format_properties2_len(
         &self,
         physical_device: vk::PhysicalDevice,
@@ -130,19 +135,22 @@ impl GetPhysicalDeviceProperties2 {
     }
 
     #[doc = "<https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/vkGetPhysicalDeviceSparseImageFormatProperties2KHR.html>"]
+    ///
+    /// Call [`Self::get_physical_device_sparse_image_format_properties2_len()`] to query the number of elements to pass to `out`.
+    /// Be sure to [`Default::default()`]-initialize these elements and optionally set their `p_next` pointer.
     pub unsafe fn get_physical_device_sparse_image_format_properties2(
         &self,
         physical_device: vk::PhysicalDevice,
         format_info: &vk::PhysicalDeviceSparseImageFormatInfo2KHR,
-        properties: &mut [vk::SparseImageFormatProperties2KHR],
+        out: &mut [vk::SparseImageFormatProperties2KHR],
     ) {
-        let mut count = properties.len() as u32;
+        let mut count = out.len() as u32;
         self.get_physical_device_properties2_fn
             .get_physical_device_sparse_image_format_properties2_khr(
                 physical_device,
                 format_info,
                 &mut count,
-                properties.as_mut_ptr(),
+                out.as_mut_ptr(),
             );
     }
 

ash/src/instance.rs

@@ -51,6 +51,7 @@ impl Instance {
         &self.instance_fn_1_1
     }
 
+    /// Retrieve the number of elements to pass to [`Self::enumerate_physical_device_groups()`]
     pub unsafe fn enumerate_physical_device_groups_len(&self) -> VkResult<usize> {
         let mut group_count = 0;
         self.instance_fn_1_1
@@ -59,6 +60,9 @@ impl Instance {
     }
 
     #[doc = "<https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/vkEnumeratePhysicalDeviceGroups.html>"]
+    ///
+    /// Call [`Self::enumerate_physical_device_groups_len()`] to query the number of elements to pass to `out`.
+    /// Be sure to [`Default::default()`]-initialize these elements and optionally set their `p_next` pointer.
     pub unsafe fn enumerate_physical_device_groups(
         &self,
         out: &mut [vk::PhysicalDeviceGroupProperties],
@@ -116,6 +120,7 @@ impl Instance {
             .into()
     }
 
+    /// Retrieve the number of elements to pass to [`Self::get_physical_device_queue_family_properties2()`]
     pub unsafe fn get_physical_device_queue_family_properties2_len(
         &self,
         physical_device: vk::PhysicalDevice,
@@ -131,17 +136,20 @@ impl Instance {
     }
 
     #[doc = "<https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/vkGetPhysicalDeviceQueueFamilyProperties2.html>"]
+    ///
+    /// Call [`Self::get_physical_device_queue_family_properties2_len()`] to query the number of elements to pass to `out`.
+    /// Be sure to [`Default::default()`]-initialize these elements and optionally set their `p_next` pointer.
     pub unsafe fn get_physical_device_queue_family_properties2(
         &self,
         physical_device: vk::PhysicalDevice,
-        queue_family_props: &mut [vk::QueueFamilyProperties2],
+        out: &mut [vk::QueueFamilyProperties2],
     ) {
-        let mut queue_count = queue_family_props.len() as u32;
+        let mut queue_count = out.len() as u32;
         self.instance_fn_1_1
             .get_physical_device_queue_family_properties2(
                 physical_device,
                 &mut queue_count,
-                queue_family_props.as_mut_ptr(),
+                out.as_mut_ptr(),
             );
     }
 
@@ -155,6 +163,7 @@ impl Instance {
             .get_physical_device_memory_properties2(physical_device, out);
     }
 
+    /// Retrieve the number of elements to pass to [`Self::get_physical_device_sparse_image_format_properties2()`]
     pub unsafe fn get_physical_device_sparse_image_format_properties2_len(
         &self,
         physical_device: vk::PhysicalDevice,
@@ -172,6 +181,9 @@ impl Instance {
     }
 
     #[doc = "<https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/vkGetPhysicalDeviceSparseImageFormatProperties2.html>"]
+    ///
+    /// Call [`Self::get_physical_device_sparse_image_format_properties2_len()`] to query the number of elements to pass to `out`.
+    /// Be sure to [`Default::default()`]-initialize these elements and optionally set their `p_next` pointer.
     pub unsafe fn get_physical_device_sparse_image_format_properties2(
         &self,
         physical_device: vk::PhysicalDevice,