From 4ac4b0ae9fb9ff95fab0d69cc6992bce271e09dc Mon Sep 17 00:00:00 2001
From: Kevin Reid <kpreid@google.com>
Date: Wed, 11 May 2022 21:58:34 -0700
Subject: [PATCH 1/2] Add cross-references to each wgpu type's documentation.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Added:
* WebGPU specification links.
* How to create an instance, if it is not all-public-fields.
* What function or enclosing type this type is used for.

(The latter two are not present for `wgpu-types` items due to the
dependency running the wrong direction for that — I saw existing
`../wgpu/` links, but those do not work on https://docs.rs/wgpu/.)

This commit specifically does not:
* substantially revise existing language, except where necessary to fit
  the new information, or when there was an obvious trivial improvement
  like adding a link to support "how to use this".
* add similar information to the documentation of types not directly
  corresponding to the WebGPU specification
---
 wgpu-types/src/lib.rs | 200 +++++++++++++++++++++++++++++++++---
 wgpu/src/lib.rs       | 229 ++++++++++++++++++++++++++++++++++++++----
 2 files changed, 395 insertions(+), 34 deletions(-)

diff --git a/wgpu-types/src/lib.rs b/wgpu-types/src/lib.rs
index 59b202059d..2b410d4afc 100644
--- a/wgpu-types/src/lib.rs
+++ b/wgpu-types/src/lib.rs
@@ -66,6 +66,9 @@ pub enum Backend {
 }
 
 /// Power Preference when choosing a physical adapter.
+///
+/// Corresponds to [WebGPU `GPUPowerPreference`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gpupowerpreference).
 #[repr(C)]
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -125,6 +128,9 @@ impl From<Backend> for Backends {
 }
 
 /// Options for requesting adapter.
+///
+/// Corresponds to [WebGPU `GPURequestAdapterOptions`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpurequestadapteroptions).
 #[repr(C)]
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -161,6 +167,9 @@ bitflags::bitflags! {
     /// If you want to use a feature, you need to first verify that the adapter supports
     /// the feature. If the adapter does not support the feature, requesting a device with it enabled
     /// will panic.
+    ///
+    /// Corresponds to [WebGPU `GPUFeatureName`](
+    /// https://gpuweb.github.io/gpuweb/#enumdef-gpufeaturename).
     #[repr(transparent)]
     #[derive(Default)]
     pub struct Features: u64 {
@@ -616,7 +625,8 @@ impl Features {
 /// implementation needs to support more than is needed. You should ideally only request exactly
 /// what you need.
 ///
-/// See also: <https://gpuweb.github.io/gpuweb/#dictdef-gpulimits>
+/// Corresponds to [WebGPU `GPUSupportedLimits`](
+/// https://gpuweb.github.io/gpuweb/#gpusupportedlimits).
 ///
 /// [`downlevel_defaults()`]: Limits::downlevel_defaults
 #[repr(C)]
@@ -1064,6 +1074,9 @@ pub struct AdapterInfo {
 }
 
 /// Describes a [`Device`](../wgpu/struct.Device.html).
+///
+/// Corresponds to [WebGPU `GPUDeviceDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#gpudevicedescriptor).
 #[repr(C)]
 #[derive(Clone, Debug, Default)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -1096,6 +1109,9 @@ bitflags::bitflags! {
     /// These can be combined so something that is visible from both vertex and fragment shaders can be defined as:
     ///
     /// `ShaderStages::VERTEX | ShaderStages::FRAGMENT`
+    ///
+    /// Corresponds to [WebGPU `GPUShaderStageFlags`](
+    /// https://gpuweb.github.io/gpuweb/#typedefdef-gpushaderstageflags).
     #[repr(transparent)]
     pub struct ShaderStages: u32 {
         /// Binding is not visible from any shader stage.
@@ -1115,6 +1131,9 @@ bitflags::bitflags! {
 bitflags_serde_shim::impl_serde_for_bitflags!(ShaderStages);
 
 /// Dimensions of a particular texture view.
+///
+/// Corresponds to [WebGPU `GPUTextureViewDimension`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gputextureviewdimension).
 #[repr(C)]
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -1160,6 +1179,9 @@ impl TextureViewDimension {
 /// Alpha blend factor.
 ///
 /// Alpha blending is very complicated: see the OpenGL or Vulkan spec for more information.
+///
+/// Corresponds to [WebGPU `GPUBlendFactor`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gpublendfactor).
 #[repr(C)]
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -1197,6 +1219,9 @@ pub enum BlendFactor {
 /// Alpha blend operation.
 ///
 /// Alpha blending is very complicated: see the OpenGL or Vulkan spec for more information.
+///
+/// Corresponds to [WebGPU `GPUBlendOperation`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gpublendoperation).
 #[repr(C)]
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -1221,7 +1246,10 @@ impl Default for BlendOperation {
     }
 }
 
-/// Describes the blend component of a pipeline.
+/// Describes a blend component of a [`BlendState`].
+///
+/// Corresponds to [WebGPU `GPUBlendComponent`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpublendcomponent).
 #[repr(C)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -1271,9 +1299,13 @@ impl Default for BlendComponent {
     }
 }
 
-/// Describe the blend state of a render pipeline.
+/// Describe the blend state of a render pipeline,
+/// within [`ColorTargetState`].
 ///
 /// See the OpenGL or Vulkan spec for more information.
+///
+/// Corresponds to [WebGPU `GPUBlendState`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpublendstate).
 #[repr(C)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -1311,6 +1343,9 @@ impl BlendState {
 }
 
 /// Describes the color state of a render pipeline.
+///
+/// Corresponds to [WebGPU `GPUColorTargetState`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpucolortargetstate).
 #[repr(C)]
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -1341,6 +1376,9 @@ impl From<TextureFormat> for ColorTargetState {
 }
 
 /// Primitive type the input mesh is composed of.
+///
+/// Corresponds to [WebGPU `GPUPrimitiveTopology`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpuprimitivetopology).
 #[repr(C)]
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -1383,7 +1421,10 @@ impl PrimitiveTopology {
     }
 }
 
-/// Winding order which classifies the "front" face.
+/// Vertex winding order which classifies the "front" face of a triangle.
+///
+/// Corresponds to [WebGPU `GPUFrontFace`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gpufrontface).
 #[repr(C)]
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -1407,6 +1448,10 @@ impl Default for FrontFace {
 }
 
 /// Face of a vertex.
+///
+/// Corresponds to [WebGPU `GPUCullMode`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gpucullmode),
+/// except that the `"none"` value is represented using `Option<Face>` instead.
 #[repr(C)]
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -1441,6 +1486,9 @@ impl Default for PolygonMode {
 }
 
 /// Describes the state of primitive assembly and rasterization in a render pipeline.
+///
+/// Corresponds to [WebGPU `GPUPrimitiveState`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpuprimitivestate).
 #[repr(C)]
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -1479,6 +1527,9 @@ pub struct PrimitiveState {
 }
 
 /// Describes the multi-sampling state of a render pipeline.
+///
+/// Corresponds to [WebGPU `GPUMultisampleState`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpumultisamplestate).
 #[repr(C)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -1627,8 +1678,11 @@ pub enum AstcChannel {
 
 /// Underlying texture data format.
 ///
-/// If there is a conversion in the format (such as srgb -> linear), The conversion listed is for
+/// If there is a conversion in the format (such as srgb -> linear), the conversion listed here is for
 /// loading from texture in a shader. When writing to the texture, the opposite conversion takes place.
+///
+/// Corresponds to [WebGPU `GPUTextureFormat`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gputextureformat).
 #[repr(C)]
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Deserialize, Serialize))]
@@ -2176,6 +2230,9 @@ impl TextureFormat {
 
 bitflags::bitflags! {
     /// Color write mask. Disabled color channels will not be written to.
+    ///
+    /// Corresponds to [WebGPU `GPUColorWriteFlags`](
+    /// https://gpuweb.github.io/gpuweb/#typedefdef-gpucolorwriteflags).
     #[repr(transparent)]
     pub struct ColorWrites: u32 {
         /// Enable red channel writes
@@ -2203,6 +2260,11 @@ impl Default for ColorWrites {
 }
 
 /// State of the stencil operation (fixed-pipeline stage).
+///
+/// For use in [`DepthStencilState`].
+///
+/// Corresponds to a portion of [WebGPU `GPUDepthStencilState`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpudepthstencilstate).
 #[repr(C)]
 #[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -2235,6 +2297,11 @@ impl StencilState {
 }
 
 /// Describes the biasing setting for the depth target.
+///
+/// For use in [`DepthStencilState`].
+///
+/// Corresponds to a portion of [WebGPU `GPUDepthStencilState`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpudepthstencilstate).
 #[repr(C)]
 #[derive(Clone, Copy, Debug, Default, PartialEq)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -2256,6 +2323,9 @@ impl DepthBiasState {
 }
 
 /// Describes the depth/stencil state in a render pipeline.
+///
+/// Corresponds to [WebGPU `GPUDepthStencilState`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpudepthstencilstate).
 #[repr(C)]
 #[derive(Clone, Debug, PartialEq)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -2290,6 +2360,9 @@ impl DepthStencilState {
 }
 
 /// Format of indices used with pipeline.
+///
+/// Corresponds to [WebGPU `GPUIndexFormat`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gpuindexformat).
 #[repr(C)]
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Deserialize, Serialize))]
@@ -2308,6 +2381,9 @@ impl Default for IndexFormat {
 }
 
 /// Operation to perform on the stencil value.
+///
+/// Corresponds to [WebGPU `GPUStencilOperation`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gpustenciloperation).
 #[repr(C)]
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -2344,6 +2420,9 @@ impl Default for StencilOperation {
 /// Describes stencil state in a render pipeline.
 ///
 /// If you are not using stencil state, set this to [`StencilFaceState::IGNORE`].
+///
+/// Corresponds to [WebGPU `GPUStencilFaceState`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpustencilfacestate).
 #[repr(C)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -2385,6 +2464,9 @@ impl Default for StencilFaceState {
 }
 
 /// Comparison function used for depth and stencil operations.
+///
+/// Corresponds to [WebGPU `GPUCompareFunction`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gpucomparefunction).
 #[repr(C)]
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -2420,6 +2502,9 @@ impl CompareFunction {
 }
 
 /// Rate that determines when vertex data is advanced.
+///
+/// Corresponds to [WebGPU `GPUVertexStepMode`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gpuvertexstepmode).
 #[repr(C)]
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -2443,6 +2528,9 @@ impl Default for VertexStepMode {
 /// Arrays of these can be made with the [`vertex_attr_array`]
 /// macro. Vertex attributes are assumed to be tightly packed.
 ///
+/// Corresponds to [WebGPU `GPUVertexAttribute`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpuvertexattribute).
+///
 /// [`vertex_attr_array`]: ../wgpu/macro.vertex_attr_array.html
 #[repr(C)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
@@ -2458,7 +2546,10 @@ pub struct VertexAttribute {
     pub shader_location: ShaderLocation,
 }
 
-/// Vertex Format for a Vertex Attribute (input).
+/// Vertex Format for a [`VertexAttribute`] (input).
+///
+/// Corresponds to [WebGPU `GPUVertexFormat`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gpuvertexformat).
 #[repr(C)]
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -2574,6 +2665,9 @@ bitflags::bitflags! {
     ///
     /// The usages determine what kind of memory the buffer is allocated from and what
     /// actions the buffer can partake in.
+    ///
+    /// Corresponds to [WebGPU `GPUBufferUsageFlags`](
+    /// https://gpuweb.github.io/gpuweb/#typedefdef-gpubufferusageflags).
     #[repr(transparent)]
     pub struct BufferUsages: u32 {
         /// Allow a buffer to be mapped for reading using [`Buffer::map_async`] + [`Buffer::get_mapped_range`].
@@ -2611,6 +2705,9 @@ bitflags::bitflags! {
 bitflags_serde_shim::impl_serde_for_bitflags!(BufferUsages);
 
 /// Describes a [`Buffer`](../wgpu/struct.Buffer.html).
+///
+/// Corresponds to [WebGPU `GPUBufferDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpubufferdescriptor).
 #[repr(C)]
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -2641,6 +2738,9 @@ impl<L> BufferDescriptor<L> {
 }
 
 /// Describes a [`CommandEncoder`](../wgpu/struct.CommandEncoder.html).
+///
+/// Corresponds to [WebGPU `GPUCommandEncoderDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpucommandencoderdescriptor).
 #[repr(C)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
 #[cfg_attr(feature = "replay", derive(Deserialize))]
@@ -2692,6 +2792,9 @@ bitflags::bitflags! {
     ///
     /// The usages determine what kind of memory the texture is allocated from and what
     /// actions the texture can partake in.
+    ///
+    /// Corresponds to [WebGPU `GPUTextureUsageFlags`](
+    /// https://gpuweb.github.io/gpuweb/#typedefdef-gputextureusageflags).
     #[repr(transparent)]
     pub struct TextureUsages: u32 {
         /// Allows a texture to be the source in a [`CommandEncoder::copy_texture_to_buffer`] or
@@ -2810,6 +2913,9 @@ impl Color {
 }
 
 /// Dimensionality of a texture.
+///
+/// Corresponds to [WebGPU `GPUTextureDimension`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gputexturedimension).
 #[repr(C)]
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -2827,6 +2933,9 @@ pub enum TextureDimension {
 }
 
 /// Origin of a copy to/from a texture.
+///
+/// Corresponds to [WebGPU `GPUOrigin3D`](
+/// https://gpuweb.github.io/gpuweb/#typedefdef-gpuorigin3d).
 #[repr(C)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -2853,6 +2962,9 @@ impl Default for Origin3d {
 }
 
 /// Extent of a texture related operation.
+///
+/// Corresponds to [WebGPU `GPUExtent3D`](
+/// https://gpuweb.github.io/gpuweb/#typedefdef-gpuextent3d).
 #[repr(C)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -3039,6 +3151,9 @@ fn test_max_mips() {
 }
 
 /// Describes a [`Texture`](../wgpu/struct.Texture.html).
+///
+/// Corresponds to [WebGPU `GPUTextureDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gputexturedescriptor).
 #[repr(C)]
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -3125,6 +3240,9 @@ impl<L> TextureDescriptor<L> {
 }
 
 /// Kind of data the texture holds.
+///
+/// Corresponds to [WebGPU `GPUTextureAspect`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gputextureaspect).
 #[repr(C)]
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -3146,6 +3264,9 @@ impl Default for TextureAspect {
 }
 
 /// How edges should be handled in texture addressing.
+///
+/// Corresponds to [WebGPU `GPUAddressMode`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gpuaddressmode).
 #[repr(C)]
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -3182,6 +3303,9 @@ impl Default for AddressMode {
 }
 
 /// Texel mixing mode when sampling between texels.
+///
+/// Corresponds to [WebGPU `GPUFilterMode`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gpufiltermode).
 #[repr(C)]
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -3218,6 +3342,9 @@ pub struct PushConstantRange {
 }
 
 /// Describes a [`CommandBuffer`](../wgpu/struct.CommandBuffer.html).
+///
+/// Corresponds to [WebGPU `GPUCommandBufferDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpucommandbufferdescriptor).
 #[repr(C)]
 #[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -3237,6 +3364,9 @@ impl<L> CommandBufferDescriptor<L> {
 }
 
 /// Describes the depth/stencil attachment for render bundles.
+///
+/// Corresponds to a portion of [WebGPU `GPURenderBundleEncoderDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpurenderbundleencoderdescriptor).
 #[repr(C)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "trace", derive(serde::Serialize))]
@@ -3251,6 +3381,9 @@ pub struct RenderBundleDepthStencil {
 }
 
 /// Describes a [`RenderBundle`](../wgpu/struct.RenderBundle.html).
+///
+/// Corresponds to [WebGPU `GPURenderBundleDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpurenderbundledescriptor).
 #[repr(C)]
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -3285,6 +3418,9 @@ impl<T> Default for RenderBundleDescriptor<Option<T>> {
 /// | 32x16x8    | RGBA8  | 4               | 1 * 1 * 1        | 32 * 4 = 128 padded to 256 = Some(256) | None                         |
 /// | 256x256    | BC3    | 16              | 4 * 4 * 1        | 16 * (256 / 4) = 1024 = Some(1024)     | None                         |
 /// | 64x64x8    | BC3    | 16              | 4 * 4 * 1        | 16 * (64 / 4) = 256 = Some(256)        | 64 / 4 = 16 = Some(16)       |
+///
+/// Corresponds to [WebGPU `GPUImageDataLayout`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpuimagedatalayout).
 #[repr(C)]
 #[derive(Clone, Copy, Debug, Default)]
 #[cfg_attr(feature = "trace", derive(serde::Serialize))]
@@ -3325,7 +3461,8 @@ pub struct ImageDataLayout {
 
 /// Specific type of a buffer binding.
 ///
-/// WebGPU spec: <https://gpuweb.github.io/gpuweb/#enumdef-gpubufferbindingtype>
+/// Corresponds to [WebGPU `GPUBufferBindingType`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gpubufferbindingtype).
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
 #[cfg_attr(feature = "replay", derive(Deserialize))]
@@ -3371,7 +3508,8 @@ impl Default for BufferBindingType {
 
 /// Specific type of a sample in a texture binding.
 ///
-/// WebGPU spec: <https://gpuweb.github.io/gpuweb/#enumdef-gputexturesampletype>
+/// Corresponds to [WebGPU `GPUTextureSampleType`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gputexturesampletype).
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
 #[cfg_attr(feature = "replay", derive(Deserialize))]
@@ -3422,7 +3560,10 @@ impl Default for TextureSampleType {
 
 /// Specific type of a sample in a texture binding.
 ///
-/// WebGPU spec: <https://gpuweb.github.io/gpuweb/#enumdef-gpustoragetextureaccess>
+/// For use in [`BindingType::StorageTexture`].
+///
+/// Corresponds to [WebGPU `GPUStorageTextureAccess`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gpustoragetextureaccess).
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
 #[cfg_attr(feature = "replay", derive(Deserialize))]
@@ -3455,7 +3596,10 @@ pub enum StorageTextureAccess {
 
 /// Specific type of a sampler binding.
 ///
-/// WebGPU spec: <https://gpuweb.github.io/gpuweb/#enumdef-gpusamplerbindingtype>
+/// For use in [`BindingType::Sampler`].
+///
+/// Corresponds to [WebGPU `GPUSamplerBindingType`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gpusamplerbindingtype).
 #[repr(C)]
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -3474,16 +3618,18 @@ pub enum SamplerBindingType {
 
 /// Specific type of a binding.
 ///
-/// WebGPU spec: the enum of
-/// - <https://gpuweb.github.io/gpuweb/#dictdef-gpubufferbindinglayout>
-/// - <https://gpuweb.github.io/gpuweb/#dictdef-gpusamplerbindinglayout>
-/// - <https://gpuweb.github.io/gpuweb/#dictdef-gputexturebindinglayout>
-/// - <https://gpuweb.github.io/gpuweb/#dictdef-gpustoragetexturebindinglayout>
+/// For use in [`BindGroupLayoutEntry`].
+///
+/// Corresponds to WebGPU's mutually exclusive fields within [`GPUBindGroupLayoutEntry`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpubindgrouplayoutentry).
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
 #[cfg_attr(feature = "replay", derive(Deserialize))]
 pub enum BindingType {
     /// A buffer binding.
+    ///
+    /// Corresponds to [WebGPU `GPUBufferBindingLayout`](
+    /// https://gpuweb.github.io/gpuweb/#dictdef-gpubufferbindinglayout).
     Buffer {
         /// Sub-type of the buffer binding.
         ty: BufferBindingType,
@@ -3509,6 +3655,9 @@ pub enum BindingType {
     /// layout(binding = 0)
     /// uniform sampler s;
     /// ```
+    ///
+    /// Corresponds to [WebGPU `GPUSamplerBindingLayout`](
+    /// https://gpuweb.github.io/gpuweb/#dictdef-gpusamplerbindinglayout).
     Sampler(SamplerBindingType),
     /// A texture binding.
     ///
@@ -3517,6 +3666,9 @@ pub enum BindingType {
     /// layout(binding = 0)
     /// uniform texture2D t;
     /// ```
+    ///
+    /// Corresponds to [WebGPU `GPUTextureBindingLayout`](
+    /// https://gpuweb.github.io/gpuweb/#dictdef-gputexturebindinglayout).
     Texture {
         /// Sample type of the texture binding.
         sample_type: TextureSampleType,
@@ -3535,6 +3687,9 @@ pub enum BindingType {
     /// ```
     /// Note that the texture format must be specified in the shader as well.
     /// A list of valid formats can be found in the specification here: <https://www.khronos.org/registry/OpenGL/specs/gl/GLSLangSpec.4.60.html#layout-qualifiers>
+    ///
+    /// Corresponds to [WebGPU `GPUStorageTextureBindingLayout`](
+    /// https://gpuweb.github.io/gpuweb/#dictdef-gpustoragetexturebindinglayout).
     StorageTexture {
         /// Allowed access to this texture.
         access: StorageTextureAccess,
@@ -3558,6 +3713,9 @@ impl BindingType {
 }
 
 /// Describes a single binding inside a bind group.
+///
+/// Corresponds to [WebGPU `GPUBindGroupLayoutEntry`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpubindgrouplayoutentry).
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
 #[cfg_attr(feature = "replay", derive(Deserialize))]
@@ -3579,6 +3737,9 @@ pub struct BindGroupLayoutEntry {
 }
 
 /// View of a buffer which can be used to copy to/from a texture.
+///
+/// Corresponds to [WebGPU `GPUImageCopyBuffer`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpuimagecopybuffer).
 #[repr(C)]
 #[derive(Clone, Debug)]
 #[cfg_attr(feature = "trace", derive(serde::Serialize))]
@@ -3591,6 +3752,9 @@ pub struct ImageCopyBuffer<B> {
 }
 
 /// View of a texture which can be used to copy to/from a buffer/texture.
+///
+/// Corresponds to [WebGPU `GPUImageCopyTexture`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpuimagecopytexture).
 #[repr(C)]
 #[derive(Clone, Debug)]
 #[cfg_attr(feature = "trace", derive(serde::Serialize))]
@@ -3678,6 +3842,9 @@ pub enum SamplerBorderColor {
 }
 
 /// Describes how to create a QuerySet.
+///
+/// Corresponds to [WebGPU `GPUQuerySetDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpuquerysetdescriptor).
 #[derive(Clone, Debug)]
 #[cfg_attr(feature = "trace", derive(serde::Serialize))]
 #[cfg_attr(feature = "replay", derive(serde::Deserialize))]
@@ -3703,6 +3870,9 @@ impl<L> QuerySetDescriptor<L> {
 }
 
 /// Type of query contained in a QuerySet.
+///
+/// Corresponds to [WebGPU `GPUQueryType`](
+/// https://gpuweb.github.io/gpuweb/#enumdef-gpuquerytype).
 #[derive(Copy, Clone, Debug)]
 #[cfg_attr(feature = "trace", derive(serde::Serialize))]
 #[cfg_attr(feature = "replay", derive(serde::Deserialize))]
diff --git a/wgpu/src/lib.rs b/wgpu/src/lib.rs
index 8e23f43efc..d8fd6e0e7b 100644
--- a/wgpu/src/lib.rs
+++ b/wgpu/src/lib.rs
@@ -507,6 +507,8 @@ trait Context: Debug + Send + Sized + Sync {
 /// Its primary use is to create [`Adapter`]s and [`Surface`]s.
 ///
 /// Does not have to be kept alive.
+///
+/// Corresponds to [WebGPU `GPU`](https://gpuweb.github.io/gpuweb/#gpu-interface).
 #[derive(Debug)]
 pub struct Instance {
     context: Arc<C>,
@@ -518,6 +520,8 @@ pub struct Instance {
 /// on the host system by using [`Adapter::request_device`].
 ///
 /// Does not have to be kept alive.
+///
+/// Corresponds to [WebGPU `GPUAdapter`](https://gpuweb.github.io/gpuweb/#gpu-adapter).
 #[derive(Debug)]
 pub struct Adapter {
     context: Arc<C>,
@@ -538,6 +542,8 @@ impl Drop for Adapter {
 /// These are then used in commands, which are submitted to a [`Queue`].
 ///
 /// A device may be requested from an adapter with [`Adapter::request_device`].
+///
+/// Corresponds to [WebGPU `GPUDevice`](https://gpuweb.github.io/gpuweb/#gpu-device).
 #[derive(Debug)]
 pub struct Device {
     context: Arc<C>,
@@ -617,6 +623,8 @@ impl MapContext {
 ///
 /// Created with [`Device::create_buffer`] or
 /// [`DeviceExt::create_buffer_init`](util::DeviceExt::create_buffer_init).
+///
+/// Corresponds to [WebGPU `GPUBuffer`](https://gpuweb.github.io/gpuweb/#buffer-interface).
 #[derive(Debug)]
 pub struct Buffer {
     context: Arc<C>,
@@ -639,7 +647,9 @@ pub struct BufferSlice<'a> {
 
 /// Handle to a texture on the GPU.
 ///
-/// Created by calling [`Device::create_texture`]
+/// It can be created with [`Device::create_texture`].
+///
+/// Corresponds to [WebGPU `GPUTexture`](https://gpuweb.github.io/gpuweb/#texture-interface).
 #[derive(Debug)]
 pub struct Texture {
     context: Arc<C>,
@@ -651,6 +661,8 @@ pub struct Texture {
 ///
 /// A `TextureView` object describes a texture and associated metadata needed by a
 /// [`RenderPipeline`] or [`BindGroup`].
+///
+/// Corresponds to [WebGPU `GPUTextureView`](https://gpuweb.github.io/gpuweb/#gputextureview).
 #[derive(Debug)]
 pub struct TextureView {
     context: Arc<C>,
@@ -662,6 +674,10 @@ pub struct TextureView {
 /// A `Sampler` object defines how a pipeline will sample from a [`TextureView`]. Samplers define
 /// image filters (including anisotropy) and address (wrapping) modes, among other things. See
 /// the documentation for [`SamplerDescriptor`] for more information.
+///
+/// It can be created with [`Device::create_sampler`].
+///
+/// Corresponds to [WebGPU `GPUSampler`](https://gpuweb.github.io/gpuweb/#sampler-interface).
 #[derive(Debug)]
 pub struct Sampler {
     context: Arc<C>,
@@ -700,6 +716,11 @@ impl Drop for Surface {
 /// create a [`BindGroupDescriptor`] object, which in turn can be used to create a [`BindGroup`]
 /// object with [`Device::create_bind_group`]. A series of `BindGroupLayout`s can also be used to
 /// create a [`PipelineLayoutDescriptor`], which can be used to create a [`PipelineLayout`].
+///
+/// It can be created with [`Device::create_bind_group_layout`].
+///
+/// Corresponds to [WebGPU `GPUBindGroupLayout`](
+/// https://gpuweb.github.io/gpuweb/#gpubindgrouplayout).
 #[derive(Debug)]
 pub struct BindGroupLayout {
     context: Arc<C>,
@@ -720,6 +741,8 @@ impl Drop for BindGroupLayout {
 /// [`BindGroupLayout`]. It can be created with [`Device::create_bind_group`]. A `BindGroup` can
 /// be bound to a particular [`RenderPass`] with [`RenderPass::set_bind_group`], or to a
 /// [`ComputePass`] with [`ComputePass::set_bind_group`].
+///
+/// Corresponds to [WebGPU `GPUBindGroup`](https://gpuweb.github.io/gpuweb/#gpubindgroup).
 #[derive(Debug)]
 pub struct BindGroup {
     context: Arc<C>,
@@ -737,8 +760,11 @@ impl Drop for BindGroup {
 /// Handle to a compiled shader module.
 ///
 /// A `ShaderModule` represents a compiled shader module on the GPU. It can be created by passing
-/// valid SPIR-V source code to [`Device::create_shader_module`]. Shader modules are used to define
-/// programmable stages of a pipeline.
+/// source code to [`Device::create_shader_module`] or valid SPIR-V binary to
+/// [`Device::create_shader_module_spirv`]. Shader modules are used to define programmable stages
+/// of a pipeline.
+///
+/// Corresponds to [WebGPU `GPUShaderModule`](https://gpuweb.github.io/gpuweb/#shader-module).
 #[derive(Debug)]
 pub struct ShaderModule {
     context: Arc<C>,
@@ -782,7 +808,10 @@ pub enum ShaderSource<'a> {
     Wgsl(Cow<'a, str>),
 }
 
-/// Descriptor for a shader module.
+/// Descriptor for use with [`Device::create_shader_module`].
+///
+/// Corresponds to [WebGPU `GPUShaderModuleDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpushadermoduledescriptor).
 pub struct ShaderModuleDescriptor<'a> {
     /// Debug label of the shader module. This will show up in graphics debuggers for easy identification.
     pub label: Label<'a>,
@@ -801,6 +830,9 @@ pub struct ShaderModuleDescriptorSpirV<'a> {
 /// Handle to a pipeline layout.
 ///
 /// A `PipelineLayout` object describes the available binding groups of a pipeline.
+/// It can be created with [`Device::create_pipeline_layout`].
+///
+/// Corresponds to [WebGPU `GPUPipelineLayout`](https://gpuweb.github.io/gpuweb/#gpupipelinelayout).
 #[derive(Debug)]
 pub struct PipelineLayout {
     context: Arc<C>,
@@ -818,7 +850,9 @@ impl Drop for PipelineLayout {
 /// Handle to a rendering (graphics) pipeline.
 ///
 /// A `RenderPipeline` object represents a graphics pipeline and its stages, bindings, vertex
-/// buffers and targets. A `RenderPipeline` may be created with [`Device::create_render_pipeline`].
+/// buffers and targets. It can be created with [`Device::create_render_pipeline`].
+///
+/// Corresponds to [WebGPU `GPURenderPipeline`](https://gpuweb.github.io/gpuweb/#render-pipeline).
 #[derive(Debug)]
 pub struct RenderPipeline {
     context: Arc<C>,
@@ -849,7 +883,9 @@ impl RenderPipeline {
 /// Handle to a compute pipeline.
 ///
 /// A `ComputePipeline` object represents a compute pipeline and its single shader stage.
-/// A `ComputePipeline` may be created with [`Device::create_compute_pipeline`].
+/// It can be created with [`Device::create_compute_pipeline`].
+///
+/// Corresponds to [WebGPU `GPUComputePipeline`](https://gpuweb.github.io/gpuweb/#compute-pipeline).
 #[derive(Debug)]
 pub struct ComputePipeline {
     context: Arc<C>,
@@ -882,6 +918,8 @@ impl ComputePipeline {
 /// A `CommandBuffer` represents a complete sequence of commands that may be submitted to a command
 /// queue with [`Queue::submit`]. A `CommandBuffer` is obtained by recording a series of commands to
 /// a [`CommandEncoder`] and then calling [`CommandEncoder::finish`].
+///
+/// Corresponds to [WebGPU `GPUCommandBuffer`](https://gpuweb.github.io/gpuweb/#command-buffer).
 #[derive(Debug)]
 pub struct CommandBuffer {
     context: Arc<C>,
@@ -905,6 +943,8 @@ impl Drop for CommandBuffer {
 ///
 /// When finished recording, call [`CommandEncoder::finish`] to obtain a [`CommandBuffer`] which may
 /// be submitted for execution.
+///
+/// Corresponds to [WebGPU `GPUCommandEncoder`](https://gpuweb.github.io/gpuweb/#command-encoder).
 #[derive(Debug)]
 pub struct CommandEncoder {
     context: Arc<C>,
@@ -922,6 +962,11 @@ impl Drop for CommandEncoder {
 }
 
 /// In-progress recording of a render pass.
+///
+/// It can be created with [`CommandEncoder::begin_render_pass`].
+///
+/// Corresponds to [WebGPU `GPURenderPassEncoder`](
+/// https://gpuweb.github.io/gpuweb/#render-pass-encoder).
 #[derive(Debug)]
 pub struct RenderPass<'a> {
     id: <C as Context>::RenderPassId,
@@ -929,6 +974,11 @@ pub struct RenderPass<'a> {
 }
 
 /// In-progress recording of a compute pass.
+///
+/// It can be created with [`CommandEncoder::begin_compute_pass`].
+///
+/// Corresponds to [WebGPU `GPUComputePassEncoder`](
+/// https://gpuweb.github.io/gpuweb/#compute-pass-encoder).
 #[derive(Debug)]
 pub struct ComputePass<'a> {
     id: <C as Context>::ComputePassId,
@@ -937,10 +987,15 @@ pub struct ComputePass<'a> {
 
 /// Encodes a series of GPU operations into a reusable "render bundle".
 ///
-/// It only supports a handful of render commands, but it makes them reusable. [`RenderBundle`]s
-/// can be executed onto a [`CommandEncoder`] using [`RenderPass::execute_bundles`].
+/// It only supports a handful of render commands, but it makes them reusable.
+/// It can be created with [`Device::create_render_bundle_encoder`].
+/// It can be executed onto a [`CommandEncoder`] using [`RenderPass::execute_bundles`].
 ///
-/// Executing a [`RenderBundle`] is often more efficient than issuing the underlying commands manually.
+/// Executing a [`RenderBundle`] is often more efficient than issuing the underlying commands
+/// manually.
+///
+/// Corresponds to [WebGPU `GPURenderBundleEncoder`](
+/// https://gpuweb.github.io/gpuweb/#gpurenderbundleencoder).
 #[derive(Debug)]
 pub struct RenderBundleEncoder<'a> {
     context: Arc<C>,
@@ -953,10 +1008,13 @@ pub struct RenderBundleEncoder<'a> {
 
 /// Pre-prepared reusable bundle of GPU operations.
 ///
-/// It only supports a handful of render commands, but it makes them reusable. [`RenderBundle`]s
-/// can be executed onto a [`CommandEncoder`] using [`RenderPass::execute_bundles`].
+/// It only supports a handful of render commands, but it makes them reusable. Executing a
+/// [`RenderBundle`] is often more efficient than issuing the underlying commands manually.
+///
+/// It can be created by use of a [`RenderBundleEncoder`], and executed onto a [`CommandEncoder`]
+/// using [`RenderPass::execute_bundles`].
 ///
-/// Executing a [`RenderBundle`] is often more efficient than issuing the underlying commands manually.
+/// Corresponds to [WebGPU `GPURenderBundle`](https://gpuweb.github.io/gpuweb/#render-bundle).
 #[derive(Debug)]
 pub struct RenderBundle {
     context: Arc<C>,
@@ -972,6 +1030,10 @@ impl Drop for RenderBundle {
 }
 
 /// Handle to a query set.
+///
+/// It can be created with [`Device::create_query_set`].
+///
+/// Corresponds to [WebGPU `GPUQuerySet`](https://gpuweb.github.io/gpuweb/#queryset).
 pub struct QuerySet {
     context: Arc<C>,
     id: <C as Context>::QuerySetId,
@@ -989,6 +1051,9 @@ impl Drop for QuerySet {
 ///
 /// A `Queue` executes recorded [`CommandBuffer`] objects and provides convenience methods
 /// for writing to [buffers](Queue::write_buffer) and [textures](Queue::write_texture).
+/// It can be created along with a [`Device`] by calling [`Adapter::request_device`].
+///
+/// Corresponds to [WebGPU `GPUQueue`](https://gpuweb.github.io/gpuweb/#gpu-queue).
 #[derive(Debug)]
 pub struct Queue {
     context: Arc<C>,
@@ -996,6 +1061,9 @@ pub struct Queue {
 }
 
 /// Resource that can be bound to a pipeline.
+///
+/// Corresponds to [WebGPU `GPUBindingResource`](
+/// https://gpuweb.github.io/gpuweb/#typedefdef-gpubindingresource).
 #[non_exhaustive]
 #[derive(Clone, Debug)]
 pub enum BindingResource<'a> {
@@ -1037,6 +1105,9 @@ pub enum BindingResource<'a> {
 }
 
 /// Describes the segment of a buffer to bind.
+///
+/// Corresponds to [WebGPU `GPUBufferBinding`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpubufferbinding).
 #[derive(Clone, Debug)]
 pub struct BufferBinding<'a> {
     /// The buffer to bind.
@@ -1054,6 +1125,8 @@ pub struct BufferBinding<'a> {
 /// Operation to perform to the output attachment at the start of a renderpass.
 ///
 /// The render target must be cleared at least once before its content is loaded.
+///
+/// Corresponds to [WebGPU `GPULoadOp`](https://gpuweb.github.io/gpuweb/#enumdef-gpuloadop).
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "trace", derive(serde::Serialize))]
 #[cfg_attr(feature = "replay", derive(serde::Deserialize))]
@@ -1091,6 +1164,11 @@ impl<V: Default> Default for Operations<V> {
 }
 
 /// Describes a color attachment to a [`RenderPass`].
+///
+/// For use with [`RenderPassDescriptor`].
+///
+/// Corresponds to [WebGPU `GPURenderPassColorAttachment`](
+/// https://gpuweb.github.io/gpuweb/#color-attachments).
 #[derive(Clone, Debug)]
 pub struct RenderPassColorAttachment<'a> {
     /// The view to use as an attachment.
@@ -1102,6 +1180,11 @@ pub struct RenderPassColorAttachment<'a> {
 }
 
 /// Describes a depth/stencil attachment to a [`RenderPass`].
+///
+/// For use with [`RenderPassDescriptor`].
+///
+/// Corresponds to [WebGPU `GPURenderPassDepthStencilAttachment`](
+/// https://gpuweb.github.io/gpuweb/#depth-stencil-attachments).
 #[derive(Clone, Debug)]
 pub struct RenderPassDepthStencilAttachment<'a> {
     /// The view to use as an attachment.
@@ -1114,25 +1197,65 @@ pub struct RenderPassDepthStencilAttachment<'a> {
 
 // The underlying types are also exported so that documentation shows up for them
 
-/// Object label.
+/// Object debugging label.
 pub type Label<'a> = Option<&'a str>;
 pub use wgt::RequestAdapterOptions as RequestAdapterOptionsBase;
 /// Additional information required when requesting an adapter.
+///
+/// For use with [`Instance::request_adapter`].
+///
+/// Corresponds to [WebGPU `GPURequestAdapterOptions`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpurequestadapteroptions).
 pub type RequestAdapterOptions<'a> = RequestAdapterOptionsBase<&'a Surface>;
 /// Describes a [`Device`].
+///
+/// For use with [`Adapter::request_device`].
+///
+/// Corresponds to [WebGPU `GPUDeviceDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpudevicedescriptor).
 pub type DeviceDescriptor<'a> = wgt::DeviceDescriptor<Label<'a>>;
 /// Describes a [`Buffer`].
+///
+/// For use with [`Device::create_buffer`].
+///
+/// Corresponds to [WebGPU `GPUBufferDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpubufferdescriptor).
 pub type BufferDescriptor<'a> = wgt::BufferDescriptor<Label<'a>>;
 /// Describes a [`CommandEncoder`].
+///
+/// For use with [`Device::create_command_encoder`].
+///
+/// Corresponds to [WebGPU `GPUCommandEncoderDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpucommandencoderdescriptor).
 pub type CommandEncoderDescriptor<'a> = wgt::CommandEncoderDescriptor<Label<'a>>;
 /// Describes a [`RenderBundle`].
+///
+/// For use with [`RenderBundleEncoder::finish`].
+///
+/// Corresponds to [WebGPU `GPURenderBundleDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpurenderbundledescriptor).
 pub type RenderBundleDescriptor<'a> = wgt::RenderBundleDescriptor<Label<'a>>;
 /// Describes a [`Texture`].
+///
+/// For use with [`Device::create_texture`].
+///
+/// Corresponds to [WebGPU `GPUTextureDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gputexturedescriptor).
 pub type TextureDescriptor<'a> = wgt::TextureDescriptor<Label<'a>>;
 /// Describes a [`QuerySet`].
+///
+/// For use with [`Device::create_query_set`].
+///
+/// Corresponds to [WebGPU `GPUQuerySetDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpuquerysetdescriptor).
 pub type QuerySetDescriptor<'a> = wgt::QuerySetDescriptor<Label<'a>>;
 
 /// Describes a [`TextureView`].
+///
+/// For use with [`Texture::create_view`].
+///
+/// Corresponds to [WebGPU `GPUTextureViewDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gputextureviewdescriptor).
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct TextureViewDescriptor<'a> {
     /// Debug label of the texture view. This will show up in graphics debuggers for easy identification.
@@ -1158,9 +1281,12 @@ pub struct TextureViewDescriptor<'a> {
     pub array_layer_count: Option<NonZeroU32>,
 }
 
-/// Describes a pipeline layout.
+/// Describes a [`PipelineLayout`].
+///
+/// For use with [`Device::create_pipeline_layout`].
 ///
-/// A `PipelineLayoutDescriptor` can be used to create a pipeline layout.
+/// Corresponds to [WebGPU `GPUPipelineLayoutDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpupipelinelayoutdescriptor).
 #[derive(Clone, Debug, Default)]
 pub struct PipelineLayoutDescriptor<'a> {
     /// Debug label of the pipeline layout. This will show up in graphics debuggers for easy identification.
@@ -1176,7 +1302,12 @@ pub struct PipelineLayoutDescriptor<'a> {
     pub push_constant_ranges: &'a [PushConstantRange],
 }
 
-/// Describes a [`Sampler`]
+/// Describes a [`Sampler`].
+///
+/// For use with [`Device::create_sampler`].
+///
+/// Corresponds to [WebGPU `GPUSamplerDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpusamplerdescriptor).
 #[derive(Clone, Debug, PartialEq)]
 pub struct SamplerDescriptor<'a> {
     /// Debug label of the sampler. This will show up in graphics debuggers for easy identification.
@@ -1224,7 +1355,11 @@ impl Default for SamplerDescriptor<'_> {
     }
 }
 
-/// Bindable resource and the slot to bind it to.
+/// An element of a [`BindGroupDescriptor`], consisting of a bindable resource
+/// and the slot to bind it to.
+///
+/// Corresponds to [WebGPU `GPUBindGroupEntry`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpubindgroupentry).
 #[derive(Clone, Debug)]
 pub struct BindGroupEntry<'a> {
     /// Slot for which binding provides resource. Corresponds to an entry of the same
@@ -1235,6 +1370,11 @@ pub struct BindGroupEntry<'a> {
 }
 
 /// Describes a group of bindings and the resources to be bound.
+///
+/// For use with [`Device::create_bind_group`].
+///
+/// Corresponds to [WebGPU `GPUBindGroupDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpubindgroupdescriptor).
 #[derive(Clone, Debug)]
 pub struct BindGroupDescriptor<'a> {
     /// Debug label of the bind group. This will show up in graphics debuggers for easy identification.
@@ -1247,8 +1387,13 @@ pub struct BindGroupDescriptor<'a> {
 
 /// Describes the attachments of a render pass.
 ///
+/// For use with [`CommandEncoder::begin_render_pass`].
+///
 /// Note: separate lifetimes are needed because the texture views
 /// have to live as long as the pass is recorded, while everything else doesn't.
+///
+/// Corresponds to [WebGPU `GPURenderPassDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpurenderpassdescriptor).
 #[derive(Clone, Debug, Default)]
 pub struct RenderPassDescriptor<'a, 'b> {
     /// Debug label of the render pass. This will show up in graphics debuggers for easy identification.
@@ -1260,6 +1405,11 @@ pub struct RenderPassDescriptor<'a, 'b> {
 }
 
 /// Describes how the vertex buffer is interpreted.
+///
+/// For use in [`VertexState`].
+///
+/// Corresponds to [WebGPU `GPUVertexBufferLayout`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpurenderpassdescriptor).
 #[derive(Clone, Debug, Hash, Eq, PartialEq)]
 pub struct VertexBufferLayout<'a> {
     /// The stride, in bytes, between elements of this buffer.
@@ -1270,7 +1420,12 @@ pub struct VertexBufferLayout<'a> {
     pub attributes: &'a [VertexAttribute],
 }
 
-/// Describes the vertex process in a render pipeline.
+/// Describes the vertex processing in a render pipeline.
+///
+/// For use in [`RenderPipelineDescriptor`].
+///
+/// Corresponds to [WebGPU `GPUVertexState`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpuvertexstate).
 #[derive(Clone, Debug)]
 pub struct VertexState<'a> {
     /// The compiled shader module for this stage.
@@ -1282,7 +1437,12 @@ pub struct VertexState<'a> {
     pub buffers: &'a [VertexBufferLayout<'a>],
 }
 
-/// Describes the fragment process in a render pipeline.
+/// Describes the fragment processing in a render pipeline.
+///
+/// For use in [`RenderPipelineDescriptor`].
+///
+/// Corresponds to [WebGPU `GPUFragmentState`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpufragmentstate).
 #[derive(Clone, Debug)]
 pub struct FragmentState<'a> {
     /// The compiled shader module for this stage.
@@ -1295,6 +1455,11 @@ pub struct FragmentState<'a> {
 }
 
 /// Describes a render (graphics) pipeline.
+///
+/// For use with [`Device::create_render_pipeline`].
+///
+/// Corresponds to [WebGPU `GPURenderPipelineDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpurenderpipelinedescriptor).
 #[derive(Clone, Debug)]
 pub struct RenderPipelineDescriptor<'a> {
     /// Debug label of the pipeline. This will show up in graphics debuggers for easy identification.
@@ -1317,6 +1482,11 @@ pub struct RenderPipelineDescriptor<'a> {
 }
 
 /// Describes the attachments of a compute pass.
+///
+/// For use with [`CommandEncoder::begin_compute_pass`].
+///
+/// Corresponds to [WebGPU `GPUComputePassDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpucomputepassdescriptor).
 #[derive(Clone, Debug, Default)]
 pub struct ComputePassDescriptor<'a> {
     /// Debug label of the compute pass. This will show up in graphics debuggers for easy identification.
@@ -1324,6 +1494,11 @@ pub struct ComputePassDescriptor<'a> {
 }
 
 /// Describes a compute pipeline.
+///
+/// For use with [`Device::create_compute_pipeline`].
+///
+/// Corresponds to [WebGPU `GPUComputePipelineDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpucomputepipelinedescriptor).
 #[derive(Clone, Debug)]
 pub struct ComputePipelineDescriptor<'a> {
     /// Debug label of the pipeline. This will show up in graphics debuggers for easy identification.
@@ -1339,13 +1514,24 @@ pub struct ComputePipelineDescriptor<'a> {
 
 pub use wgt::ImageCopyBuffer as ImageCopyBufferBase;
 /// View of a buffer which can be used to copy to/from a texture.
+///
+/// Corresponds to [WebGPU `GPUImageCopyBuffer`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpuimagecopybuffer).
 pub type ImageCopyBuffer<'a> = ImageCopyBufferBase<&'a Buffer>;
 
 pub use wgt::ImageCopyTexture as ImageCopyTextureBase;
 /// View of a texture which can be used to copy to/from a buffer/texture.
+///
+/// Corresponds to [WebGPU `GPUImageCopyTexture`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpuimagecopytexture).
 pub type ImageCopyTexture<'a> = ImageCopyTextureBase<&'a Texture>;
 
 /// Describes a [`BindGroupLayout`].
+///
+/// For use with [`Device::create_bind_group_layout`].
+///
+/// Corresponds to [WebGPU `GPUBindGroupLayoutDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpubindgrouplayoutdescriptor).
 #[derive(Clone, Debug)]
 pub struct BindGroupLayoutDescriptor<'a> {
     /// Debug label of the bind group layout. This will show up in graphics debuggers for easy identification.
@@ -1356,6 +1542,11 @@ pub struct BindGroupLayoutDescriptor<'a> {
 }
 
 /// Describes a [`RenderBundleEncoder`].
+///
+/// For use with [`Device::create_render_bundle_encoder`].
+///
+/// Corresponds to [WebGPU `GPURenderBundleEncoderDescriptor`](
+/// https://gpuweb.github.io/gpuweb/#dictdef-gpurenderbundleencoderdescriptor).
 #[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
 pub struct RenderBundleEncoderDescriptor<'a> {
     /// Debug label of the render bundle encoder. This will show up in graphics debuggers for easy identification.

From 86bc0fbea752264fbdfebf7a8d1388b5a2e289f1 Mon Sep 17 00:00:00 2001
From: Jim Blandy <jimb@red-bean.com>
Date: Thu, 12 May 2022 20:15:02 -0700
Subject: [PATCH 2/2] Two more fixes to WebGPU spec links.

---
 wgpu-types/src/lib.rs | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/wgpu-types/src/lib.rs b/wgpu-types/src/lib.rs
index 2b410d4afc..b20f5b979b 100644
--- a/wgpu-types/src/lib.rs
+++ b/wgpu-types/src/lib.rs
@@ -1378,7 +1378,7 @@ impl From<TextureFormat> for ColorTargetState {
 /// Primitive type the input mesh is composed of.
 ///
 /// Corresponds to [WebGPU `GPUPrimitiveTopology`](
-/// https://gpuweb.github.io/gpuweb/#dictdef-gpuprimitivetopology).
+/// https://gpuweb.github.io/gpuweb/#enumdef-gpuprimitivetopology).
 #[repr(C)]
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "trace", derive(Serialize))]
@@ -2996,12 +2996,13 @@ impl Default for Extent3d {
 }
 
 impl Extent3d {
-    /// Calculates the [physical size] is backing an texture of the given format and extent.
-    /// This includes padding to the block width and height of the format.
+    /// Calculates the [physical size] backing a texture of the given
+    /// format and extent.  This includes padding to the block width
+    /// and height of the format.
     ///
     /// This is the texture extent that you must upload at when uploading to _mipmaps_ of compressed textures.
     ///
-    /// [physical size]: https://gpuweb.github.io/gpuweb/#physical-size
+    /// [physical size]: https://gpuweb.github.io/gpuweb/#physical-miplevel-specific-texture-extent
     pub fn physical_size(&self, format: TextureFormat) -> Self {
         let (block_width, block_height) = format.describe().block_dimensions;
         let block_width = block_width as u32;