Merge #1639

1639: Doc fixes for wgpu r=cwfitzgerald a=jimblandy This PR makes `cargo doc --all-features` work without errors. Commits are organized for ease of review (and for revision, if I screwed something up). Co-authored-by: Jim Blandy <jimb@red-bean.com>
2026-04-22 03:02:01 -04:00 · 2021-07-12 21:27:52 +00:00
parent c41efb0256 51dc5b407c
commit 6c8e046238
5 changed files with 33 additions and 27 deletions
--- a/wgpu-types/src/lib.rs
+++ b/wgpu-types/src/lib.rs
@@ -2522,8 +2522,9 @@ impl Extent3d {
 pub struct TextureDescriptor<L> {
    /// Debug label of the texture. This will show up in graphics debuggers for easy identification.
    pub label: L,
-    /// Size of the texture. For a regular 1D/2D texture, the unused sizes will be 1. For 2DArray textures, Z is the
-    /// number of 2D textures in that array.
+    /// Size of the texture. All components must be greater than zero. For a
+    /// regular 1D/2D texture, the unused sizes will be 1. For 2DArray textures,
+    /// Z is the number of 2D textures in that array.
    pub size: Extent3d,
    /// Mip count of texture. For a texture with no extra mips, this must be 1.
    pub mip_level_count: u32,
@@ -3012,7 +3013,7 @@ pub struct BindGroupLayoutEntry {
    pub ty: BindingType,
    /// If this value is Some, indicates this entry is an array. Array size must be 1 or greater.
    ///
-    /// If this value is Some and `ty` is `BindingType::Texture`, [`Features::SAMPLED_TEXTURE_BINDING_ARRAY`] must be supported.
+    /// If this value is Some and `ty` is `BindingType::Texture`, [`Features::TEXTURE_BINDING_ARRAY`] must be supported.
    ///
    /// If this value is Some and `ty` is any other variant, bind group creation will fail.
    #[cfg_attr(any(feature = "trace", feature = "replay"), serde(default))]
--- a/wgpu/src/lib.rs
+++ b/wgpu/src/lib.rs
@@ -585,7 +585,8 @@ impl MapContext {

 /// Handle to a GPU-accessible buffer.
 ///
-/// Created with [`Device::create_buffer`] or [DeviceExt::create_buffer_init](util::DeviceExt::create_buffer_init)
+/// Created with [`Device::create_buffer`] or
+/// [`DeviceExt::create_buffer_init`](util::DeviceExt::create_buffer_init).
 #[derive(Debug)]
 pub struct Buffer {
    context: Arc<C>,
@@ -993,7 +994,7 @@ pub enum BindingResource<'a> {
    TextureView(&'a TextureView),
    /// Binding is backed by an array of textures.
    ///
-    /// [`Features::SAMPLED_TEXTURE_BINDING_ARRAY`] must be supported to use this feature.
+    /// [`Features::TEXTURE_BINDING_ARRAY`] must be supported to use this feature.
    ///
    /// Corresponds to [`wgt::BindingType::Texture`] and [`wgt::BindingType::StorageTexture`] with
    /// [`BindGroupLayoutEntry::count`] set to Some.
@@ -1584,7 +1585,7 @@ impl Device {
    /// This function passes binary data to the backend as-is and can potentially result in a
    /// driver crash or bogus behaviour. No attempt is made to ensure that data is valid SPIR-V.
    ///
-    /// See also [`crate::include_spirv_raw!`] and [`crate::make_spirv_raw`].
+    /// See also [`include_spirv_raw!`] and [`util::make_spirv_raw`].
    pub unsafe fn create_shader_module_spirv(
        &self,
        desc: &ShaderModuleDescriptorSpirV,
@@ -2245,7 +2246,7 @@ impl CommandEncoder {
    /// Issue a timestamp command at this point in the queue.
    /// The timestamp will be written to the specified query set, at the specified index.
    ///
-    /// Must be multiplied by [`Device::get_timestamp_period`] to get
+    /// Must be multiplied by [`Queue::get_timestamp_period`] to get
    /// the value in nanoseconds. Absolute values have no meaning,
    /// but timestamps can be subtracted to get the time it takes
    /// for a string of operations to complete.
@@ -2263,7 +2264,7 @@ impl CommandEncoder {
 impl CommandEncoder {
    /// Resolve a query set, writing the results into the supplied destination buffer.
    ///
-    /// Queries may be between 8 and 40 bytes each. See [`PipelineStatisticsType`] for more information.
+    /// Queries may be between 8 and 40 bytes each. See [`PipelineStatisticsTypes`] for more information.
    pub fn resolve_query_set(
        &mut self,
        query_set: &QuerySet,
@@ -2332,7 +2333,7 @@ impl<'a> RenderPass<'a> {
    /// [`RenderPass`] will use `buffer` as one of the source vertex buffers.
    ///
    /// The `slot` refers to the index of the matching descriptor in
-    /// [`VertexStateDescriptor::vertex_buffers`].
+    /// [`VertexState::buffers`].
    ///
    /// [`draw`]: RenderPass::draw
    /// [`draw_indexed`]: RenderPass::draw_indexed
@@ -2651,7 +2652,7 @@ impl<'a> RenderPass<'a> {
    /// Issue a timestamp command at this point in the queue. The
    /// timestamp will be written to the specified query set, at the specified index.
    ///
-    /// Must be multiplied by [`Device::get_timestamp_period`] to get
+    /// Must be multiplied by [`Queue::get_timestamp_period`] to get
    /// the value in nanoseconds. Absolute values have no meaning,
    /// but timestamps can be subtracted to get the time it takes
    /// for a string of operations to complete.
@@ -2757,7 +2758,7 @@ impl<'a> ComputePass<'a> {
 impl<'a> ComputePass<'a> {
    /// Issue a timestamp command at this point in the queue. The timestamp will be written to the specified query set, at the specified index.
    ///
-    /// Must be multiplied by [`Device::get_timestamp_period`] to get
+    /// Must be multiplied by [`Queue::get_timestamp_period`] to get
    /// the value in nanoseconds. Absolute values have no meaning,
    /// but timestamps can be subtracted to get the time it takes
    /// for a string of operations to complete.
@@ -2842,7 +2843,7 @@ impl<'a> RenderBundleEncoder<'a> {
    /// [`RenderBundleEncoder`] will use `buffer` as one of the source vertex buffers.
    ///
    /// The `slot` refers to the index of the matching descriptor in
-    /// [`VertexStateDescriptor::vertex_buffers`].
+    /// [`VertexState::buffers`].
    ///
    /// [`draw`]: RenderBundleEncoder::draw
    /// [`draw_indexed`]: RenderBundleEncoder::draw_indexed
--- a/wgpu/src/macros.rs
+++ b/wgpu/src/macros.rs
@@ -1,13 +1,13 @@
 //! Convenience macros

-/// Macro to produce an array of [VertexAttribute](crate::VertexAttribute).
+/// Macro to produce an array of [`VertexAttribute`](crate::VertexAttribute).
 ///
 /// Output has type: `[VertexAttribute; _]`. Usage is as follows:
 /// ```
 /// # use wgpu::vertex_attr_array;
 /// let attrs = vertex_attr_array![0 => Float32x2, 1 => Float32, 2 => Uint16x4];
 /// ```
-/// This example specifies a list of three [VertexAttribute](crate::VertexAttribute),
+/// This example specifies a list of three [`VertexAttribute`](crate::VertexAttribute),
 /// each with the given `shader_location` and `format`.
 /// Offsets are calculated automatically.
 #[macro_export]
@@ -57,9 +57,11 @@ macro_rules! include_spirv {
    };
 }

-/// Macro to load raw SPIR-V data statically, for use with [`wgpu::Features::SPIRV_SHADER_PASSTHROUGH`].
+/// Macro to load raw SPIR-V data statically, for use with [`Features::SPIRV_SHADER_PASSTHROUGH`].
 ///
 /// It ensures the word alignment as well as the magic number.
+///
+/// [`Features::SPIRV_SHADER_PASSTHROUGH`]: crate::Features::SPIRV_SHADER_PASSTHROUGH
 #[macro_export]
 macro_rules! include_spirv_raw {
    ($($token:tt)*) => {
--- a/wgpu/src/util/encoder.rs
+++ b/wgpu/src/util/encoder.rs
@@ -4,7 +4,7 @@ use wgt::{BufferAddress, DynamicOffset, IndexFormat};

 use crate::{BindGroup, Buffer, BufferSlice, RenderBundleEncoder, RenderPass, RenderPipeline};

-/// Methods shared by `RenderPass` and `RenderBundleEncoder`
+/// Methods shared by [`RenderPass`] and [`RenderBundleEncoder`].
 pub trait RenderEncoder<'a> {
    /// Sets the active bind group for a given bind group index. The bind group layout
    /// in the active pipeline when any `draw()` function is called must match the layout of this bind group.
@@ -19,36 +19,36 @@ pub trait RenderEncoder<'a> {

    /// Sets the active index buffer.
    ///
-    /// Subsequent calls to [`draw_indexed`](RenderBundleEncoder::draw_indexed) on this [`RenderBundleEncoder`] will
+    /// Subsequent calls to [`draw_indexed`](RenderEncoder::draw_indexed) on this [`RenderEncoder`] will
    /// use `buffer` as the source index buffer.
    fn set_index_buffer(&mut self, buffer_slice: BufferSlice<'a>, index_format: IndexFormat);

    /// Assign a vertex buffer to a slot.
    ///
    /// Subsequent calls to [`draw`] and [`draw_indexed`] on this
-    /// [`RenderBundleEncoder`] will use `buffer` as one of the source vertex buffers.
+    /// [`RenderEncoder`] will use `buffer` as one of the source vertex buffers.
    ///
    /// The `slot` refers to the index of the matching descriptor in
-    /// [VertexStateDescriptor::vertex_buffers](crate::VertexStateDescriptor::vertex_buffers).
+    /// [VertexState::buffers](crate::VertexState::buffers).
    ///
-    /// [`draw`]: RenderBundleEncoder::draw
-    /// [`draw_indexed`]: RenderBundleEncoder::draw_indexed
+    /// [`draw`]: RenderEncoder::draw
+    /// [`draw_indexed`]: RenderEncoder::draw_indexed
    fn set_vertex_buffer(&mut self, slot: u32, buffer_slice: BufferSlice<'a>);

    /// Draws primitives from the active vertex buffer(s).
    ///
-    /// The active vertex buffers can be set with [`RenderBundleEncoder::set_vertex_buffer`].
+    /// The active vertex buffers can be set with [`RenderEncoder::set_vertex_buffer`].
    fn draw(&mut self, vertices: Range<u32>, instances: Range<u32>);

    /// Draws indexed primitives using the active index buffer and the active vertex buffers.
    ///
-    /// The active index buffer can be set with [`RenderBundleEncoder::set_index_buffer`], while the active
-    /// vertex buffers can be set with [`RenderBundleEncoder::set_vertex_buffer`].
+    /// The active index buffer can be set with [`RenderEncoder::set_index_buffer`], while the active
+    /// vertex buffers can be set with [`RenderEncoder::set_vertex_buffer`].
    fn draw_indexed(&mut self, indices: Range<u32>, base_vertex: i32, instances: Range<u32>);

    /// Draws primitives from the active vertex buffer(s) based on the contents of the `indirect_buffer`.
    ///
-    /// The active vertex buffers can be set with [`RenderBundleEncoder::set_vertex_buffer`].
+    /// The active vertex buffers can be set with [`RenderEncoder::set_vertex_buffer`].
    ///
    /// The structure expected in `indirect_buffer` is the following:
    ///
@@ -66,8 +66,8 @@ pub trait RenderEncoder<'a> {
    /// Draws indexed primitives using the active index buffer and the active vertex buffers,
    /// based on the contents of the `indirect_buffer`.
    ///
-    /// The active index buffer can be set with [`RenderBundleEncoder::set_index_buffer`], while the active
-    /// vertex buffers can be set with [`RenderBundleEncoder::set_vertex_buffer`].
+    /// The active index buffer can be set with [`RenderEncoder::set_index_buffer`], while the active
+    /// vertex buffers can be set with [`RenderEncoder::set_vertex_buffer`].
    ///
    /// The structure expected in `indirect_buffer` is the following:
    ///
--- a/wgpu/src/util/mod.rs
+++ b/wgpu/src/util/mod.rs
@@ -36,6 +36,8 @@ pub fn make_spirv(data: &[u8]) -> super::ShaderSource {

 /// Version of [`make_spirv`] intended for use with [`Device::create_shader_module_spirv`].
 /// Returns raw slice instead of ShaderSource.
+///
+/// [`Device::create_shader_module_spirv`]: crate::Device::create_shader_module_spirv
 pub fn make_spirv_raw(data: &[u8]) -> Cow<[u32]> {
    const MAGIC_NUMBER: u32 = 0x0723_0203;
    assert_eq!(