From a2cd2b92b301aea8fc9f080042c6f12381348294 Mon Sep 17 00:00:00 2001 From: Jim Blandy Date: Sat, 27 Apr 2024 13:21:29 -0700 Subject: [PATCH] [hal] Fix `cargo doc --document-private-items`. Check in CI. (#5617) --- .github/workflows/ci.yml | 2 +- CHANGELOG.md | 1 + wgpu-hal/src/dx12/conv.rs | 2 +- wgpu-hal/src/dx12/mod.rs | 2 +- wgpu-hal/src/metal/mod.rs | 10 +++++----- wgpu-hal/src/vulkan/adapter.rs | 11 +++++++++++ 6 files changed, 20 insertions(+), 8 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 735759e79..5d410cbaa 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -237,7 +237,7 @@ jobs: set -e # wgpu_core package - cargo +${{ env.DOCS_RUST_VERSION }} doc --target ${{ matrix.target }} --all-features --no-deps --package wgpu-core --document-private-items + cargo +${{ env.DOCS_RUST_VERSION }} doc --target ${{ matrix.target }} --all-features --no-deps --package wgpu-core --package wgpu-hal --document-private-items # We run minimal checks on the MSRV of the core crates, ensuring that # its dependency tree does not cause issues for firefox. diff --git a/CHANGELOG.md b/CHANGELOG.md index e24b99dca..4648a3219 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -167,6 +167,7 @@ By @atlv24 and @cwfitzgerald in [#5154](https://github.com/gfx-rs/wgpu/pull/5154 ### Documentation +- Improved `wgpu_hal` documentation. By @jimblandy in [#5516](https://github.com/gfx-rs/wgpu/pull/5516), [#5524](https://github.com/gfx-rs/wgpu/pull/5524), [#5562](https://github.com/gfx-rs/wgpu/pull/5562), [#5563](https://github.com/gfx-rs/wgpu/pull/5563), [#5566](https://github.com/gfx-rs/wgpu/pull/5566), [#5617](https://github.com/gfx-rs/wgpu/pull/5617), [#5618](https://github.com/gfx-rs/wgpu/pull/5618) - Add mention of primitive restart in the description of `PrimitiveState::strip_index_format`. By @cpsdqs in [#5350](https://github.com/gfx-rs/wgpu/pull/5350) - Document precise behaviour of `SourceLocation`. By @stefnotch in [#5386](https://github.com/gfx-rs/wgpu/pull/5386) - Give short example of WGSL `push_constant` syntax. By @waywardmonkeys in [#5393](https://github.com/gfx-rs/wgpu/pull/5393) diff --git a/wgpu-hal/src/dx12/conv.rs b/wgpu-hal/src/dx12/conv.rs index 2b6c1d959..b09ea7608 100644 --- a/wgpu-hal/src/dx12/conv.rs +++ b/wgpu-hal/src/dx12/conv.rs @@ -224,7 +224,7 @@ pub fn map_polygon_mode(mode: wgt::PolygonMode) -> d3d12_ty::D3D12_FILL_MODE { } /// D3D12 doesn't support passing factors ending in `_COLOR` for alpha blending -/// (see https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ns-d3d12-d3d12_render_target_blend_desc). +/// (see ). /// Therefore this function takes an additional `is_alpha` argument /// which if set will return an equivalent `_ALPHA` factor. fn map_blend_factor(factor: wgt::BlendFactor, is_alpha: bool) -> d3d12_ty::D3D12_BLEND { diff --git a/wgpu-hal/src/dx12/mod.rs b/wgpu-hal/src/dx12/mod.rs index 735732ef2..9f021bc24 100644 --- a/wgpu-hal/src/dx12/mod.rs +++ b/wgpu-hal/src/dx12/mod.rs @@ -440,7 +440,7 @@ impl Texture { } } - /// see https://learn.microsoft.com/en-us/windows/win32/direct3d12/subresources#plane-slice + /// see fn calc_subresource(&self, mip_level: u32, array_layer: u32, plane: u32) -> u32 { mip_level + (array_layer + plane * self.array_layer_count()) * self.mip_level_count } diff --git a/wgpu-hal/src/metal/mod.rs b/wgpu-hal/src/metal/mod.rs index 72a19b2fc..7d547cfe3 100644 --- a/wgpu-hal/src/metal/mod.rs +++ b/wgpu-hal/src/metal/mod.rs @@ -651,7 +651,7 @@ struct BufferResource { /// Buffers with the [`wgt::BufferBindingType::Storage`] binding type can /// hold WGSL runtime-sized arrays. When one does, we must pass its size to /// shader entry points to implement bounds checks and WGSL's `arrayLength` - /// function. See [`device::CompiledShader::sized_bindings`] for details. + /// function. See `device::CompiledShader::sized_bindings` for details. /// /// [`Storage`]: wgt::BufferBindingType::Storage binding_size: Option, @@ -682,12 +682,12 @@ struct PipelineStageInfo { /// The buffer argument table index at which we pass runtime-sized arrays' buffer sizes. /// - /// See [`device::CompiledShader::sized_bindings`] for more details. + /// See `device::CompiledShader::sized_bindings` for more details. sizes_slot: Option, /// Bindings of all WGSL `storage` globals that contain runtime-sized arrays. /// - /// See [`device::CompiledShader::sized_bindings`] for more details. + /// See `device::CompiledShader::sized_bindings` for more details. sized_bindings: Vec, } @@ -803,7 +803,7 @@ struct CommandState { /// /// Specifically: /// - /// - The keys are ['ResourceBinding`] values (that is, the WGSL `@group` + /// - The keys are [`ResourceBinding`] values (that is, the WGSL `@group` /// and `@binding` attributes) for `var` global variables in the /// current module that contain runtime-sized arrays. /// @@ -815,7 +815,7 @@ struct CommandState { /// of the buffers listed in [`stage_infos.S.sized_bindings`], which we must /// pass to the entry point. /// - /// See [`device::CompiledShader::sized_bindings`] for more details. + /// See `device::CompiledShader::sized_bindings` for more details. /// /// [`ResourceBinding`]: naga::ResourceBinding storage_buffer_length_map: rustc_hash::FxHashMap, diff --git a/wgpu-hal/src/vulkan/adapter.rs b/wgpu-hal/src/vulkan/adapter.rs index cf15f5d2f..21219361f 100644 --- a/wgpu-hal/src/vulkan/adapter.rs +++ b/wgpu-hal/src/vulkan/adapter.rs @@ -35,6 +35,8 @@ fn indexing_features() -> wgt::Features { /// [`PhysicalDeviceFeatures::from_extensions_and_requested_features`] /// constructs an value of this type indicating which Vulkan features to /// enable, based on the `wgpu_types::Features` requested. +/// +/// [`Instance::expose_adapter`]: super::Instance::expose_adapter #[derive(Debug, Default)] pub struct PhysicalDeviceFeatures { /// Basic Vulkan 1.0 features. @@ -86,6 +88,9 @@ pub struct PhysicalDeviceFeatures { /// /// However, we do populate this when creating a device if /// [`Features::RAY_TRACING_ACCELERATION_STRUCTURE`] is requested. + /// + /// [`Instance::expose_adapter`]: super::Instance::expose_adapter + /// [`Features::RAY_TRACING_ACCELERATION_STRUCTURE`]: wgt::Features::RAY_TRACING_ACCELERATION_STRUCTURE buffer_device_address: Option, /// Features provided by `VK_KHR_ray_query`, @@ -95,6 +100,8 @@ pub struct PhysicalDeviceFeatures { /// this from `vkGetPhysicalDeviceFeatures2`. /// /// However, we do populate this when creating a device if ray tracing is requested. + /// + /// [`Instance::expose_adapter`]: super::Instance::expose_adapter ray_query: Option, /// Features provided by `VK_KHR_zero_initialize_workgroup_memory`, promoted @@ -181,6 +188,7 @@ impl PhysicalDeviceFeatures { /// [`Features`]: wgt::Features /// [`DownlevelFlags`]: wgt::DownlevelFlags /// [`PrivateCapabilities`]: super::PrivateCapabilities + /// [`add_to_device_create_builder`]: PhysicalDeviceFeatures::add_to_device_create_builder /// [`DeviceCreateInfoBuilder`]: vk::DeviceCreateInfoBuilder /// [`Adapter::required_device_extensions`]: super::Adapter::required_device_extensions fn from_extensions_and_requested_features( @@ -459,6 +467,9 @@ impl PhysicalDeviceFeatures { /// Given `self`, together with the instance and physical device it was /// built from, and a `caps` also built from those, determine which wgpu /// features and downlevel flags the device can support. + /// + /// [`Features`]: wgt::Features + /// [`DownlevelFlags`]: wgt::DownlevelFlags fn to_wgpu( &self, instance: &ash::Instance,