Add annotations for the types hal types return

cwfitzgerald · ErichDonGubler · commit 0dbe5fb28e6c · 2025-07-16T15:10:00.000-04:00
diff --git a/wgpu-hal/src/gles/mod.rs b/wgpu-hal/src/gles/mod.rs
@@ -101,17 +101,17 @@ pub use fence::Fence;
 #[cfg(not(any(windows, webgl)))]
 pub use self::egl::{AdapterContext, AdapterContextLock};
 #[cfg(not(any(windows, webgl)))]
-use self::egl::{Instance, Surface};
+pub use self::egl::{Instance, Surface};
 
 #[cfg(webgl)]
 pub use self::web::AdapterContext;
 #[cfg(webgl)]
-use self::web::{Instance, Surface};
+pub use self::web::{Instance, Surface};
 
 #[cfg(windows)]
 use self::wgl::AdapterContext;
 #[cfg(windows)]
-use self::wgl::{Instance, Surface};
+pub use self::wgl::{Instance, Surface};
 
 use alloc::{boxed::Box, string::String, string::ToString as _, sync::Arc, vec::Vec};
 use core::{
diff --git a/wgpu/src/api/adapter.rs b/wgpu/src/api/adapter.rs
@@ -66,12 +66,12 @@ impl Adapter {
         }
     }
 
-    /// Create a wgpu [`Device`] and [`Queue`] from a wgpu-hal `OpenDevice`
+    /// Create a wgpu [`Device`] and [`Queue`] from a wgpu-hal [`hal::OpenDevice`].
     ///
     /// # Safety
     ///
     /// - `hal_device` must be created from this adapter internal handle.
-    /// - `desc.features` must be a subset of `hal_device` features.
+    /// - `desc.features` must be a subset of `hal_device`'s supported features.
     #[cfg(wgpu_core)]
     pub unsafe fn create_device_from_hal<A: wgc::hal_api::HalApi>(
         &self,
@@ -103,6 +103,15 @@ impl Adapter {
     /// Returns a guard that dereferences to the type of the hal backend
     /// which implements [`A::Adapter`].
     ///
+    /// # Types
+    ///
+    /// The returned type depends on the backend:
+    ///
+    #[doc = crate::hal_type_vulkan!("Adapter")]
+    #[doc = crate::hal_type_metal!("Adapter")]
+    #[doc = crate::hal_type_dx12!("Adapter")]
+    #[doc = crate::hal_type_gles!("Adapter")]
+    ///
     /// # Errors
     ///
     /// This method will return None if:
diff --git a/wgpu/src/api/blas.rs b/wgpu/src/api/blas.rs
@@ -162,6 +162,15 @@ impl Blas {
     /// Returns a guard that dereferences to the type of the hal backend
     /// which implements [`A::AccelerationStructure`].
     ///
+    /// # Types
+    ///
+    /// The returned type depends on the backend:
+    ///
+    #[doc = crate::hal_type_vulkan!("AccelerationStructure")]
+    #[doc = crate::hal_type_metal!("AccelerationStructure")]
+    #[doc = crate::hal_type_dx12!("AccelerationStructure")]
+    #[doc = crate::hal_type_gles!("AccelerationStructure")]
+    ///
     /// # Deadlocks
     ///
     /// - The returned guard holds a read-lock on a device-local "destruction"
diff --git a/wgpu/src/api/buffer.rs b/wgpu/src/api/buffer.rs
@@ -208,6 +208,15 @@ impl Buffer {
     /// Returns a guard that dereferences to the type of the hal backend
     /// which implements [`A::Buffer`].
     ///
+    /// # Types
+    ///
+    /// The returned type depends on the backend:
+    ///
+    #[doc = crate::hal_type_vulkan!("Buffer")]
+    #[doc = crate::hal_type_metal!("Buffer")]
+    #[doc = crate::hal_type_dx12!("Buffer")]
+    #[doc = crate::hal_type_gles!("Buffer")]
+    ///
     /// # Deadlocks
     ///
     /// - The returned guard holds a read-lock on a device-local "destruction"
diff --git a/wgpu/src/api/command_encoder.rs b/wgpu/src/api/command_encoder.rs
@@ -232,14 +232,31 @@ impl CommandEncoder {
         );
     }
 
-    /// Returns the inner hal CommandEncoder using a callback. The hal command encoder will be `None` if the
-    /// backend type argument does not match with this wgpu CommandEncoder
+    /// Get the [`wgpu_hal`] command encoder from this `CommandEncoder`.
     ///
-    /// This method will start the wgpu_core level command recording.
+    /// The returned command encoder will be ready to record onto.
+    ///
+    /// # Errors
+    ///
+    /// This method will pass in [`None`] if:
+    /// - The encoder is not from the backend specified by `A`.
+    /// - The encoder is from the `webgpu` or `custom` backend.
+    ///
+    /// # Types
+    ///
+    /// The callback argument depends on the backend:
+    ///
+    #[doc = crate::hal_type_vulkan!("CommandEncoder")]
+    #[doc = crate::hal_type_metal!("CommandEncoder")]
+    #[doc = crate::hal_type_dx12!("CommandEncoder")]
+    #[doc = crate::hal_type_gles!("CommandEncoder")]
     ///
     /// # Safety
     ///
-    /// - The raw handle obtained from the hal CommandEncoder must not be manually destroyed
+    /// - The raw handle obtained from the `A::CommandEncoder` must not be manually destroyed.
+    /// - You must not end the command buffer; wgpu will do it when you call finish.
+    /// - The wgpu command encoder must not be interacted with in any way while recording is
+    ///   happening to the wgpu_hal or backend command encoder.
     #[cfg(wgpu_core)]
     pub unsafe fn as_hal_mut<
         A: wgc::hal_api::HalApi,
diff --git a/wgpu/src/api/device.rs b/wgpu/src/api/device.rs
@@ -289,6 +289,15 @@ impl Device {
 
     /// Creates a [`Texture`] from a wgpu-hal Texture.
     ///
+    /// # Types
+    ///
+    /// The type of `A::Texture` depends on the backend:
+    ///
+    #[doc = crate::hal_type_vulkan!("Texture")]
+    #[doc = crate::hal_type_metal!("Texture")]
+    #[doc = crate::hal_type_dx12!("Texture")]
+    #[doc = crate::hal_type_gles!("Texture")]
+    ///
     /// # Safety
     ///
     /// - `hal_texture` must be created from this device internal handle
@@ -319,6 +328,15 @@ impl Device {
 
     /// Creates a [`Buffer`] from a wgpu-hal Buffer.
     ///
+    /// # Types
+    ///
+    /// The type of `A::Buffer` depends on the backend:
+    ///
+    #[doc = crate::hal_type_vulkan!("Buffer")]
+    #[doc = crate::hal_type_metal!("Buffer")]
+    #[doc = crate::hal_type_dx12!("Buffer")]
+    #[doc = crate::hal_type_gles!("Buffer")]
+    ///
     /// # Safety
     ///
     /// - `hal_buffer` must be created from this device internal handle
@@ -473,6 +491,15 @@ impl Device {
     /// Returns a guard that dereferences to the type of the hal backend
     /// which implements [`A::Device`].
     ///
+    /// # Types
+    ///
+    /// The returned type depends on the backend:
+    ///
+    #[doc = crate::hal_type_vulkan!("Device")]
+    #[doc = crate::hal_type_metal!("Device")]
+    #[doc = crate::hal_type_dx12!("Device")]
+    #[doc = crate::hal_type_gles!("Device")]
+    ///
     /// # Errors
     ///
     /// This method will return None if:
diff --git a/wgpu/src/api/instance.rs b/wgpu/src/api/instance.rs
@@ -307,15 +307,24 @@ impl Instance {
 /// Interop with wgpu-hal.
 #[cfg(wgpu_core)]
 impl Instance {
-    /// Create an new instance of wgpu from a wgpu-hal instance.
+    /// Create an new instance of wgpu from a wgpu-hal instance. This is often useful
+    /// when you need to do backend specific logic, or interop with an existing backend
+    /// instance.
     ///
-    /// # Arguments
+    /// # Types
+    ///
+    /// The type of `A::Instance` depends on the backend:
     ///
-    /// - `hal_instance` - wgpu-hal instance.
+    #[doc = crate::hal_type_vulkan!("Instance")]
+    #[doc = crate::hal_type_metal!("Instance")]
+    #[doc = crate::hal_type_dx12!("Instance")]
+    #[doc = crate::hal_type_gles!("Instance")]
     ///
     /// # Safety
     ///
-    /// Refer to the creation of wgpu-hal Instance for every backend.
+    /// - The `hal_instance` must be a valid and usable instance of the backend specified by `A`.
+    /// - wgpu will act like it has complete ownership of this instance, and will destroy it
+    ///   when the last reference to the instance, internal or external, is dropped.
     pub unsafe fn from_hal<A: wgc::hal_api::HalApi>(hal_instance: A::Instance) -> Self {
         Self {
             inner: unsafe {
@@ -332,6 +341,13 @@ impl Instance {
     /// Returns a guard that dereferences to the type of the hal backend
     /// which implements [`A::Instance`].
     ///
+    /// # Types
+    ///
+    #[doc = crate::hal_type_vulkan!("Instance")]
+    #[doc = crate::hal_type_metal!("Instance")]
+    #[doc = crate::hal_type_dx12!("Instance")]
+    #[doc = crate::hal_type_gles!("Instance")]
+    ///
     /// # Errors
     ///
     /// This method will return None if:
@@ -352,7 +368,16 @@ impl Instance {
             .and_then(|ctx| unsafe { ctx.instance_as_hal::<A>() })
     }
 
-    /// Converts a wgpu-hal `ExposedAdapter` to a wgpu [`Adapter`].
+    /// Converts a wgpu-hal [`hal::ExposedAdapter`] to a wgpu [`Adapter`].
+    ///
+    /// # Types
+    ///
+    /// The type of `hal_adapter.adapter` depends on the backend:
+    ///
+    #[doc = crate::hal_type_vulkan!("Adapter")]
+    #[doc = crate::hal_type_metal!("Adapter")]
+    #[doc = crate::hal_type_dx12!("Adapter")]
+    #[doc = crate::hal_type_gles!("Adapter")]
     ///
     /// # Safety
     ///
diff --git a/wgpu/src/api/queue.rs b/wgpu/src/api/queue.rs
@@ -288,6 +288,15 @@ impl Queue {
     /// Returns a guard that dereferences to the type of the hal backend
     /// which implements [`A::Queue`].
     ///
+    /// # Types
+    ///
+    /// The returned type depends on the backend:
+    ///
+    #[doc = crate::hal_type_vulkan!("Queue")]
+    #[doc = crate::hal_type_metal!("Queue")]
+    #[doc = crate::hal_type_dx12!("Queue")]
+    #[doc = crate::hal_type_gles!("Queue")]
+    ///
     /// # Errors
     ///
     /// This method will return None if:
diff --git a/wgpu/src/api/surface.rs b/wgpu/src/api/surface.rs
@@ -158,6 +158,15 @@ impl Surface<'_> {
     /// Returns a guard that dereferences to the type of the hal backend
     /// which implements [`A::Surface`].
     ///
+    /// # Types
+    ///
+    /// The returned type depends on the backend:
+    ///
+    #[doc = crate::hal_type_vulkan!("Surface")]
+    #[doc = crate::hal_type_metal!("Surface")]
+    #[doc = crate::hal_type_dx12!("Surface")]
+    #[doc = crate::hal_type_gles!("Surface")]
+    ///
     /// # Errors
     ///
     /// This method will return None if:
diff --git a/wgpu/src/api/texture.rs b/wgpu/src/api/texture.rs
@@ -27,6 +27,15 @@ impl Texture {
     /// Returns a guard that dereferences to the type of the hal backend
     /// which implements [`A::Texture`].
     ///
+    /// # Types
+    ///
+    /// The returned type depends on the backend:
+    ///
+    #[doc = crate::hal_type_vulkan!("Texture")]
+    #[doc = crate::hal_type_metal!("Texture")]
+    #[doc = crate::hal_type_dx12!("Texture")]
+    #[doc = crate::hal_type_gles!("Texture")]
+    ///
     /// # Deadlocks
     ///
     /// - The returned guard holds a read-lock on a device-local "destruction"
diff --git a/wgpu/src/api/texture_view.rs b/wgpu/src/api/texture_view.rs
@@ -39,6 +39,15 @@ impl TextureView {
     /// Returns a guard that dereferences to the type of the hal backend
     /// which implements [`A::TextureView`].
     ///
+    /// # Types
+    ///
+    /// The returned type depends on the backend:
+    ///
+    #[doc = crate::hal_type_vulkan!("TextureView")]
+    #[doc = crate::hal_type_metal!("TextureView")]
+    #[doc = crate::hal_type_dx12!("TextureView")]
+    #[doc = crate::hal_type_gles!("TextureView")]
+    ///
     /// # Deadlocks
     ///
     /// - The returned guard holds a read-lock on a device-local "destruction"
diff --git a/wgpu/src/api/tlas.rs b/wgpu/src/api/tlas.rs
@@ -38,6 +38,15 @@ impl Tlas {
     /// Returns a guard that dereferences to the type of the hal backend
     /// which implements [`A::AccelerationStructure`].
     ///
+    /// # Types
+    ///
+    /// The returned type depends on the backend:
+    ///
+    #[doc = crate::hal_type_vulkan!("AccelerationStructure")]
+    #[doc = crate::hal_type_metal!("AccelerationStructure")]
+    #[doc = crate::hal_type_dx12!("AccelerationStructure")]
+    #[doc = crate::hal_type_gles!("AccelerationStructure")]
+    ///
     /// # Deadlocks
     ///
     /// - The returned guard holds a read-lock on a device-local "destruction"
diff --git a/wgpu/src/macros.rs b/wgpu/src/macros.rs
@@ -139,6 +139,88 @@ macro_rules! include_wgsl {
     };
 }
 
+// Macros which help us generate the documentation of which hal types correspond to which backend.
+//
+// Because all backends are not compiled into the program, we cannot link to them in all situations,
+// we need to only link to the types if the backend is compiled in. These are used in #[doc] attributes
+// so cannot have more than one line, so cannot use internal cfgs.
+
+/// Helper macro to generate the documentation for dx12 hal methods, referencing the hal type.
+#[macro_export]
+#[doc(hidden)]
+#[cfg(dx12)]
+macro_rules! hal_type_dx12 {
+    ($ty: literal) => {
+        concat!("- [`hal::api::Dx12`] uses [`hal::dx12::", $ty, "`]")
+    };
+}
+/// Helper macro to generate the documentation for dx12 hal methods, referencing the hal type.
+#[macro_export]
+#[doc(hidden)]
+#[cfg(not(dx12))]
+macro_rules! hal_type_dx12 {
+    ($ty: literal) => {
+        concat!("- `hal::api::Dx12` uses `hal::dx12::", $ty, "`")
+    };
+}
+
+/// Helper macro to generate the documentation for metal hal methods, referencing the hal type.
+#[macro_export]
+#[doc(hidden)]
+#[cfg(metal)]
+macro_rules! hal_type_metal {
+    ($ty: literal) => {
+        concat!("- [`hal::api::Metal`] uses [`hal::metal::", $ty, "`]")
+    };
+}
+/// Helper macro to generate the documentation for metal hal methods, referencing the hal type.
+#[macro_export]
+#[doc(hidden)]
+#[cfg(not(metal))]
+macro_rules! hal_type_metal {
+    ($ty: literal) => {
+        concat!("- `hal::api::Metal` uses `hal::metal::", $ty, "`")
+    };
+}
+
+/// Helper macro to generate the documentation for vulkan hal methods, referencing the hal type.
+#[macro_export]
+#[doc(hidden)]
+#[cfg(vulkan)]
+macro_rules! hal_type_vulkan {
+    ($ty: literal) => {
+        concat!("- [`hal::api::Vulkan`] uses [`hal::vulkan::", $ty, "`]")
+    };
+}
+/// Helper macro to generate the documentation for vulkan hal methods, referencing the hal type.
+#[macro_export]
+#[doc(hidden)]
+#[cfg(not(vulkan))]
+macro_rules! hal_type_vulkan {
+    ($ty: literal) => {
+        concat!("- `hal::api::Vulkan` uses `hal::vulkan::", $ty, "`")
+    };
+}
+
+/// Helper macro to generate the documentation for gles hal methods, referencing the hal type.
+#[macro_export]
+#[doc(hidden)]
+#[cfg(gles)]
+macro_rules! hal_type_gles {
+    ($ty: literal) => {
+        concat!("- [`hal::api::Gles`] uses [`hal::gles::", $ty, "`]")
+    };
+}
+/// Helper macro to generate the documentation for gles hal methods, referencing the hal type.
+#[macro_export]
+#[doc(hidden)]
+#[cfg(not(gles))]
+macro_rules! hal_type_gles {
+    ($ty: literal) => {
+        concat!("- `hal::api::Gles` uses `hal::gles::", $ty, "`")
+    };
+}
+
 #[doc(hidden)]
 pub mod helpers {
     pub use alloc::borrow::Cow;
