Use intradoc-links and explain the various loading methods

ash-window/src/lib.rs

@@ -11,9 +11,9 @@ use ash::extensions::ext; // portability extensions
 ///
 /// # Safety
 ///
-/// In order for the created `SurfaceKHR` to be valid for the duration of its
+/// In order for the created [`vk::SurfaceKHR`] to be valid for the duration of its
-/// usage, the `Instance` this was called on must be dropped later than the
+/// usage, the [`Instance`] this was called on must be dropped later than the
-/// resulting `SurfaceKHR`.
+/// resulting [`vk::SurfaceKHR`].
 pub unsafe fn create_surface<L>(
     entry: &EntryCustom<L>,
     instance: &Instance,

ash/src/device.rs

@@ -489,7 +489,7 @@ impl Device {
             .result_with_success(event)
     }
 
-    /// Returns true if the event was set, and false if the event was reset, otherwise it will
+    /// Returns [`true`] if the event was set, and [`false`] if the event was reset, otherwise it will
     /// return the error code.
     #[doc = "<https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/vkGetEventStatus.html>"]
     pub unsafe fn get_event_status(&self, event: vk::Event) -> VkResult<bool> {

ash/src/entry.rs

@@ -10,7 +10,12 @@ use std::os::raw::c_char;
 use std::os::raw::c_void;
 use std::ptr;
 
-/// Function loader
+/// Holds a custom type `L` to load symbols from (usually a handle to a `dlopen`ed library),
+/// the [`vkGetInstanceProcAddr`][vk::StaticFn::get_instance_proc_addr()] loader function from
+/// this library (in [`vk::StaticFn`]), and Vulkan's "entry point" functions (resolved with `NULL`
+/// `instance`) as listed in [`vkGetInstanceProcAddr`'s description].
+///
+/// [`vkGetInstanceProcAddr`'s description]: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/vkGetInstanceProcAddr.html#_description
 #[derive(Clone)]
 pub struct EntryCustom<L> {
     static_fn: vk::StaticFn,
@@ -95,9 +100,9 @@ impl<L> EntryCustom<L> {
     #[doc = "<https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/vkCreateInstance.html>"]
     ///
     /// # Safety
-    /// In order for the created `Instance` to be valid for the duration of its
+    /// In order for the created [`Instance`] to be valid for the duration of its
-    /// usage, the `Entry` this was called on must be dropped later than the
+    /// usage, the [`Entry`](Self) this was called on must be dropped later than the
-    /// resulting `Instance`.
+    /// resulting [`Instance`].
     pub unsafe fn create_instance(
         &self,
         create_info: &vk::InstanceCreateInfo,
@@ -170,6 +175,8 @@ impl<L> EntryCustom<L> {
 
     #[deprecated = "This function is unavailable and therefore panics on Vulkan 1.0, please use `try_enumerate_instance_version` instead"]
     #[doc = "<https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/vkEnumerateInstanceVersion.html>"]
+    ///
+    /// Please use [`Self::try_enumerate_instance_version`] instead.
     pub fn enumerate_instance_version(&self) -> VkResult<u32> {
         unsafe {
             let mut api_version = 0;

ash/src/entry_libloading.rs

@@ -22,9 +22,6 @@ const LIB_PATH: &str = "libvulkan.so";
 #[cfg(any(target_os = "macos", target_os = "ios"))]
 const LIB_PATH: &str = "libvulkan.dylib";
 
-/// Function loader
-pub type Entry = EntryCustom<Arc<Library>>;
-
 #[derive(Debug)]
 pub enum LoadingError {
     LibraryLoadFailure(libloading::Error),
@@ -55,7 +52,10 @@ impl From<MissingEntryPoint> for LoadingError {
     }
 }
 
-impl EntryCustom<Arc<Library>> {
+/// Default function loader
+pub type Entry = EntryCustom<Arc<Library>>;
+
+impl Entry {
     /// Load default Vulkan library for the current platform
     ///
     /// # Safety

ash/src/instance.rs

@@ -246,9 +246,9 @@ impl Instance {
     #[doc = "<https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/vkCreateDevice.html>"]
     ///
     /// # Safety
-    /// In order for the created `Device` to be valid for the duration of its
+    /// In order for the created [`Device`] to be valid for the duration of its
-    /// usage, the `Instance` this was called on must be dropped later than the
+    /// usage, the [`Instance`] this was called on must be dropped later than the
-    /// resulting `Device`.
+    /// resulting [`Device`].
     pub unsafe fn create_device(
         &self,
         physical_device: vk::PhysicalDevice,

ash/src/lib.rs

@@ -25,6 +25,12 @@
 //! # Ok(()) }
 //! ```
 //!
+//! ## Getting started
+//! Load the Vulkan library at the default location using [`Entry::new()`][EntryCustom<_>::new()],
+//! or at a custom location using [`Entry::with_library("path/to/vulkan")`][EntryCustom<_>::with_library()].
+//! These loaders use [`libloading`]. If you wish to perform function loading yourself
+//! call [`EntryCustom::new_custom()`] with a closure turning function names
+//! into function pointers.
 
 pub use crate::device::Device;
 pub use crate::entry::{EntryCustom, InstanceError};
@@ -39,10 +45,12 @@ mod entry_libloading;
 mod instance;
 pub mod prelude;
 pub mod util;
+/// Raw Vulkan bindings and types, generated from `vk.xml`
 #[macro_use]
 pub mod vk;
 
 // macros of vk need to be defined beforehand
+/// Wrappers for Vulkan extensions
 pub mod extensions;
 
 pub trait RawPtr<T> {

ash/src/util.rs

@@ -5,12 +5,12 @@ use std::mem::size_of;
 use std::os::raw::c_void;
 use std::{io, slice};
 
-/// `Align` handles dynamic alignment. The is useful for dynamic uniform buffers where
+/// [`Align`] handles dynamic alignment. The is useful for dynamic uniform buffers where
 /// the alignment might be different. For example a 4x4 f32 matrix has a size of 64 bytes
 /// but the min alignment for a dynamic uniform buffer might be 256 bytes. A slice of `&[Mat4x4<f32>]`
 /// has a memory layout of `[[64 bytes], [64 bytes], [64 bytes]]`, but it might need to have a memory
 /// layout of `[[256 bytes], [256 bytes], [256 bytes]]`.
-/// `Align::copy_from_slice` will copy a slice of `&[T]` directly into the host memory without
+/// [`Align::copy_from_slice`] will copy a slice of `&[T]` directly into the host memory without
 /// an additional allocation and with the correct alignment.
 #[derive(Debug, Clone)]
 pub struct Align<T> {