From 54740d5982fa5ae004eee95dd6c037356ce9ea17 Mon Sep 17 00:00:00 2001 From: Jim Blandy Date: Thu, 18 Apr 2024 17:49:39 -0700 Subject: [PATCH] [core] Make `cargo doc --document-private-items` work again. Add a CI job to check it, for the future. --- .github/workflows/ci.yml | 9 +++++++++ wgpu-core/src/command/allocator.rs | 7 +++++-- wgpu-core/src/command/bundle.rs | 4 ++-- wgpu-core/src/command/mod.rs | 19 ++++++++++++++----- wgpu-core/src/device/bgl.rs | 2 +- wgpu-core/src/device/life.rs | 29 ++++++++++++----------------- wgpu-core/src/device/queue.rs | 7 ++++++- wgpu-core/src/identity.rs | 23 +++++++++-------------- wgpu-core/src/pool.rs | 8 ++++++-- wgpu-core/src/registry.rs | 3 --- wgpu-core/src/track/mod.rs | 7 ++++--- 11 files changed, 68 insertions(+), 50 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 972d02caff..9dd8086d93 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -78,6 +78,7 @@ jobs: # runtime is normally 2-8 minutes # # currently high due to documentation time problems on mac. + # https://github.com/rust-lang/rust/issues/114891 timeout-minutes: 30 strategy: @@ -229,6 +230,14 @@ jobs: # build docs cargo +${{ env.DOCS_RUST_VERSION }} doc --target ${{ matrix.target }} --all-features --no-deps + - name: check private item docs + if: matrix.kind == 'native' + shell: bash + run: | + set -e + + # wgpu_core package + cargo +${{ env.DOCS_RUST_VERSION }} doc --target ${{ matrix.target }} --all-features --no-deps --package wgpu-core --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/wgpu-core/src/command/allocator.rs b/wgpu-core/src/command/allocator.rs index f058905e35..1c07b9d106 100644 --- a/wgpu-core/src/command/allocator.rs +++ b/wgpu-core/src/command/allocator.rs @@ -11,8 +11,9 @@ use parking_lot::Mutex; /// Since a raw [`CommandEncoder`][ce] is itself a pool for allocating /// raw [`CommandBuffer`][cb]s, this is a pool of pools. /// -/// [ce]: wgpu_hal::CommandEncoder -/// [cb]: wgpu_hal::Api::CommandBuffer +/// [`wgpu_hal::CommandEncoder`]: hal::CommandEncoder +/// [ce]: hal::CommandEncoder +/// [cb]: hal::Api::CommandBuffer pub(crate) struct CommandAllocator { free_encoders: Mutex>, } @@ -28,6 +29,8 @@ impl CommandAllocator { /// /// If we have free encoders in the pool, take one of those. Otherwise, /// create a new one on `device`. + /// + /// [`wgpu_hal::CommandEncoder`]: hal::CommandEncoder pub(crate) fn acquire_encoder( &self, device: &A::Device, diff --git a/wgpu-core/src/command/bundle.rs b/wgpu-core/src/command/bundle.rs index b4ed6df8f7..d9d821c533 100644 --- a/wgpu-core/src/command/bundle.rs +++ b/wgpu-core/src/command/bundle.rs @@ -73,7 +73,7 @@ index format changes. [Gdcrbe]: crate::global::Global::device_create_render_bundle_encoder [Grbef]: crate::global::Global::render_bundle_encoder_finish -[wrpeb]: crate::command::render_ffi::wgpu_render_pass_execute_bundles +[wrpeb]: crate::command::render::render_commands::wgpu_render_pass_execute_bundles !*/ #![allow(clippy::reversed_empty_ranges)] @@ -113,7 +113,7 @@ use hal::CommandEncoder as _; use super::ArcRenderCommand; -/// https://gpuweb.github.io/gpuweb/#dom-gpurendercommandsmixin-draw +/// fn validate_draw( vertex: &[Option>], step: &[VertexStep], diff --git a/wgpu-core/src/command/mod.rs b/wgpu-core/src/command/mod.rs index 05d3ef6fde..6efc68791e 100644 --- a/wgpu-core/src/command/mod.rs +++ b/wgpu-core/src/command/mod.rs @@ -91,15 +91,17 @@ pub(crate) enum CommandEncoderStatus { /// Methods that take a command encoder id actually look up the command buffer, /// and then use its encoder. /// -/// [rce]: wgpu_hal::Api::CommandEncoder -/// [rcb]: wgpu_hal::Api::CommandBuffer +/// [rce]: hal::Api::CommandEncoder +/// [rcb]: hal::Api::CommandBuffer +/// [`CommandEncoderId`]: crate::id::CommandEncoderId pub(crate) struct CommandEncoder { /// The underlying `wgpu_hal` [`CommandEncoder`]. /// /// Successfully executed command buffers' encoders are saved in a - /// [`wgpu_hal::device::CommandAllocator`] for recycling. + /// [`CommandAllocator`] for recycling. /// - /// [`CommandEncoder`]: wgpu_hal::Api::CommandEncoder + /// [`CommandEncoder`]: hal::Api::CommandEncoder + /// [`CommandAllocator`]: crate::command::CommandAllocator raw: A::CommandEncoder, /// All the raw command buffers for our owning [`CommandBuffer`], in @@ -111,13 +113,16 @@ pub(crate) struct CommandEncoder { /// [`raw.reset_all()`][CE::ra], so the encoder and its buffers travel /// together. /// - /// [CE::ra]: wgpu_hal::CommandEncoder::reset_all + /// [CE::ra]: hal::CommandEncoder::reset_all + /// [`wgpu_hal::CommandEncoder`]: hal::CommandEncoder list: Vec, /// True if `raw` is in the "recording" state. /// /// See the documentation for [`wgpu_hal::CommandEncoder`] for /// details on the states `raw` can be in. + /// + /// [`wgpu_hal::CommandEncoder`]: hal::CommandEncoder is_open: bool, label: Option, @@ -148,6 +153,8 @@ impl CommandEncoder { /// transitions' command buffer. /// /// [l]: CommandEncoder::list + /// [`transition_buffers`]: hal::CommandEncoder::transition_buffers + /// [`transition_textures`]: hal::CommandEncoder::transition_textures fn close_and_swap(&mut self) -> Result<(), DeviceError> { if self.is_open { self.is_open = false; @@ -228,6 +235,8 @@ pub(crate) struct DestroyedTextureError(pub id::TextureId); pub struct CommandBufferMutable { /// The [`wgpu_hal::Api::CommandBuffer`]s we've built so far, and the encoder /// they belong to. + /// + /// [`wgpu_hal::Api::CommandBuffer`]: hal::Api::CommandBuffer pub(crate) encoder: CommandEncoder, /// The current state of this command buffer's encoder. diff --git a/wgpu-core/src/device/bgl.rs b/wgpu-core/src/device/bgl.rs index d606f049a3..911ac8a435 100644 --- a/wgpu-core/src/device/bgl.rs +++ b/wgpu-core/src/device/bgl.rs @@ -58,7 +58,7 @@ impl EntryMap { assert!(self.sorted); } - /// Create a new [`BindGroupLayoutEntryMap`] from a slice of [`wgt::BindGroupLayoutEntry`]s. + /// Create a new [`EntryMap`] from a slice of [`wgt::BindGroupLayoutEntry`]s. /// /// Errors if there are duplicate bindings or if any binding index is greater than /// the device's limits. diff --git a/wgpu-core/src/device/life.rs b/wgpu-core/src/device/life.rs index b41bd7326b..632fd4a70d 100644 --- a/wgpu-core/src/device/life.rs +++ b/wgpu-core/src/device/life.rs @@ -156,8 +156,7 @@ impl ResourceMaps { /// However, it's not clear that this is effective. See [#5560]. /// /// [`wgpu_hal`]: hal -/// [`CommandBuffer`]: crate::command::CommandBuffer -/// [`PendingWrites`]: crate::device::queue::PendingWrites +/// [`ResourceInfo::submission_index`]: crate::resource::ResourceInfo /// [#5560]: https://github.com/gfx-rs/wgpu/issues/5560 struct ActiveSubmission { /// The index of the submission we track. @@ -190,6 +189,8 @@ struct ActiveSubmission { /// /// Once this submission has completed, the command buffers are reset and /// the command encoder is recycled. + /// + /// [`wgpu_hal::Queue::submit`]: hal::Queue::submit encoders: Vec>, /// List of queue "on_submitted_work_done" closures to be called once this @@ -370,22 +371,19 @@ impl LifetimeTracker { /// /// Assume that all submissions up through `last_done` have completed. /// - /// - Buffers used by those submissions are now ready to map, if - /// requested. Add any buffers in the submission's [`mapped`] list to - /// [`self.ready_to_map`], where [`LifetimeTracker::handle_mapping`] will find - /// them. + /// - Buffers used by those submissions are now ready to map, if requested. + /// Add any buffers in the submission's [`mapped`] list to + /// [`self.ready_to_map`], where [`LifetimeTracker::handle_mapping`] + /// will find them. /// /// - Resources whose final use was in those submissions are now ready to - /// free. Add any resources in the submission's [`last_resources`] table - /// to [`self.free_resources`], where [`LifetimeTracker::cleanup`] will find - /// them. + /// free. Dropping the submission's [`last_resources`] table does so. /// /// Return a list of [`SubmittedWorkDoneClosure`]s to run. /// /// [`mapped`]: ActiveSubmission::mapped /// [`self.ready_to_map`]: LifetimeTracker::ready_to_map /// [`last_resources`]: ActiveSubmission::last_resources - /// [`self.free_resources`]: LifetimeTracker::free_resources /// [`SubmittedWorkDoneClosure`]: crate::device::queue::SubmittedWorkDoneClosure #[must_use] pub fn triage_submissions( @@ -733,13 +731,10 @@ impl LifetimeTracker { /// Identify resources to free, according to `trackers` and `self.suspected_resources`. /// - /// Given `trackers`, the [`Tracker`] belonging to same [`Device`] as - /// `self`, and `hub`, the [`Hub`] to which that `Device` belongs: - /// - /// Remove from `trackers` each resource mentioned in - /// [`self.suspected_resources`]. If `trackers` held the final reference to - /// that resource, add it to the appropriate free list, to be destroyed by - /// the hal: + /// Remove from `trackers`, the [`Tracker`] belonging to same [`Device`] as + /// `self`, each resource mentioned in [`self.suspected_resources`]. If + /// `trackers` held the final reference to that resource, add it to the + /// appropriate free list, to be destroyed by the hal: /// /// - Add resources used by queue submissions still in flight to the /// [`last_resources`] table of the last such submission's entry in diff --git a/wgpu-core/src/device/queue.rs b/wgpu-core/src/device/queue.rs index f524ba56d0..e3248d8bb6 100644 --- a/wgpu-core/src/device/queue.rs +++ b/wgpu-core/src/device/queue.rs @@ -152,8 +152,11 @@ pub enum TempResource { Texture(Arc>), } -/// A series of [`CommandBuffers`] that have been submitted to a +/// A series of raw [`CommandBuffer`]s that have been submitted to a /// queue, and the [`wgpu_hal::CommandEncoder`] that built them. +/// +/// [`CommandBuffer`]: hal::Api::CommandBuffer +/// [`wgpu_hal::CommandEncoder`]: hal::CommandEncoder pub(crate) struct EncoderInFlight { raw: A::CommandEncoder, cmd_buffers: Vec, @@ -197,6 +200,8 @@ pub(crate) struct PendingWrites { /// True if `command_encoder` is in the "recording" state, as /// described in the docs for the [`wgpu_hal::CommandEncoder`] /// trait. + /// + /// [`wgpu_hal::CommandEncoder`]: hal::CommandEncoder pub is_recording: bool, pub temp_resources: Vec>, diff --git a/wgpu-core/src/identity.rs b/wgpu-core/src/identity.rs index d76d29341a..dc6a8023f2 100644 --- a/wgpu-core/src/identity.rs +++ b/wgpu-core/src/identity.rs @@ -16,31 +16,26 @@ enum IdSource { /// A simple structure to allocate [`Id`] identifiers. /// -/// Calling [`alloc`] returns a fresh, never-before-seen id. Calling [`free`] +/// Calling [`alloc`] returns a fresh, never-before-seen id. Calling [`release`] /// marks an id as dead; it will never be returned again by `alloc`. /// -/// Use `IdentityManager::default` to construct new instances. +/// `IdentityValues` returns `Id`s whose index values are suitable for use as +/// indices into a `Vec` that holds those ids' referents: /// -/// `IdentityManager` returns `Id`s whose index values are suitable for use as -/// indices into a `Storage` that holds those ids' referents: +/// - Every live id has a distinct index value. Every live id's index +/// selects a distinct element in the vector. /// -/// - Every live id has a distinct index value. Each live id's index selects a -/// distinct element in the vector. -/// -/// - `IdentityManager` prefers low index numbers. If you size your vector to +/// - `IdentityValues` prefers low index numbers. If you size your vector to /// accommodate the indices produced here, the vector's length will reflect /// the highwater mark of actual occupancy. /// -/// - `IdentityManager` reuses the index values of freed ids before returning +/// - `IdentityValues` reuses the index values of freed ids before returning /// ids with new index values. Freed vector entries get reused. /// -/// See the module-level documentation for an overview of how this -/// fits together. -/// /// [`Id`]: crate::id::Id /// [`Backend`]: wgt::Backend; -/// [`alloc`]: IdentityManager::alloc -/// [`free`]: IdentityManager::free +/// [`alloc`]: IdentityValues::alloc +/// [`release`]: IdentityValues::release #[derive(Debug)] pub(super) struct IdentityValues { free: Vec<(Index, Epoch)>, diff --git a/wgpu-core/src/pool.rs b/wgpu-core/src/pool.rs index 47de6d5feb..c18c5bde15 100644 --- a/wgpu-core/src/pool.rs +++ b/wgpu-core/src/pool.rs @@ -26,9 +26,11 @@ impl ResourcePool { } } - /// Get a resource from the pool with the given entry map, or create a new one if it doesn't exist using the given constructor. + /// Get a resource from the pool with the given entry map, or create a new + /// one if it doesn't exist using the given constructor. /// - /// Behaves such that only one resource will be created for each unique entry map at any one time. + /// Behaves such that only one resource will be created for each unique + /// entry map at any one time. pub fn get_or_init(&self, key: K, constructor: F) -> Result, E> where F: FnOnce(K) -> Result, E>, @@ -96,6 +98,8 @@ impl ResourcePool { /// Remove the given entry map from the pool. /// /// Must *only* be called in the Drop impl of [`BindGroupLayout`]. + /// + /// [`BindGroupLayout`]: crate::binding_model::BindGroupLayout pub fn remove(&self, key: &K) { let hashed_key = PreHashedKey::from_key(key); diff --git a/wgpu-core/src/registry.rs b/wgpu-core/src/registry.rs index f78abcaa6a..46e5960cea 100644 --- a/wgpu-core/src/registry.rs +++ b/wgpu-core/src/registry.rs @@ -98,9 +98,6 @@ impl FutureId<'_, T> { /// Assign an existing resource to a new ID. /// /// Registers it with the registry. - /// - /// This _will_ leak the ID, and it will not be recycled again. - /// See https://github.com/gfx-rs/wgpu/issues/4912. pub fn assign_existing(self, value: &Arc) -> Id { let mut data = self.data.write(); debug_assert!(!data.contains(self.id)); diff --git a/wgpu-core/src/track/mod.rs b/wgpu-core/src/track/mod.rs index 374dfe7493..b17287932c 100644 --- a/wgpu-core/src/track/mod.rs +++ b/wgpu-core/src/track/mod.rs @@ -136,7 +136,8 @@ impl TrackerIndex { /// of a certain type. This index is separate from the resource ID for various reasons: /// - There can be multiple resource IDs pointing the the same resource. /// - IDs of dead handles can be recycled while resources are internally held alive (and tracked). -/// - The plan is to remove IDs in the long run (https://github.com/gfx-rs/wgpu/issues/5121). +/// - The plan is to remove IDs in the long run +/// ([#5121](https://github.com/gfx-rs/wgpu/issues/5121)). /// In order to produce these tracker indices, there is a shared TrackerIndexAllocator /// per resource type. Indices have the same lifetime as the internal resource they /// are associated to (alloc happens when creating the resource and free is called when @@ -639,8 +640,8 @@ impl Tracker { /// /// If a transition is needed to get the resources into the needed /// state, those transitions are stored within the tracker. A - /// subsequent call to [`BufferTracker::drain`] or - /// [`TextureTracker::drain`] is needed to get those transitions. + /// subsequent call to [`BufferTracker::drain_transitions`] or + /// [`TextureTracker::drain_transitions`] is needed to get those transitions. /// /// This is a really funky method used by Compute Passes to generate /// barriers after a call to dispatch without needing to iterate