[core] Make cargo doc --document-private-items work again.

Add a CI job to check it, for the future.

.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.

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<A: HalApi> {
     free_encoders: Mutex<Vec<A::CommandEncoder>>,
 }
@@ -28,6 +29,8 @@ impl<A: HalApi> CommandAllocator<A> {
     ///
     /// 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,

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
+/// <https://gpuweb.github.io/gpuweb/#dom-gpurendercommandsmixin-draw>
 fn validate_draw<A: HalApi>(
     vertex: &[Option<VertexState<A>>],
     step: &[VertexStep],

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<A: HalApi> {
     /// 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<A: HalApi> {
     /// [`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<A::CommandBuffer>,
 
     /// 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<String>,
@@ -148,6 +153,8 @@ impl<A: HalApi> CommandEncoder<A> {
     /// 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<A: HalApi> {
     /// 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<A>,
 
     /// The current state of this command buffer's encoder.

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.

wgpu-core/src/device/life.rs

@@ -156,8 +156,7 @@ impl<A: HalApi> ResourceMaps<A> {
 /// 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<A: HalApi> {
     /// The index of the submission we track.
@@ -190,6 +189,8 @@ struct ActiveSubmission<A: HalApi> {
     ///
     /// 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<EncoderInFlight<A>>,
 
     /// List of queue "on_submitted_work_done" closures to be called once this
@@ -370,22 +371,19 @@ impl<A: HalApi> LifetimeTracker<A> {
     ///
     /// 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<A: HalApi> LifetimeTracker<A> {
 
     /// 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

wgpu-core/src/device/queue.rs

@@ -152,8 +152,11 @@ pub enum TempResource<A: HalApi> {
     Texture(Arc<Texture<A>>),
 }
 
-/// 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<A: HalApi> {
     raw: A::CommandEncoder,
     cmd_buffers: Vec<A::CommandBuffer>,
@@ -197,6 +200,8 @@ pub(crate) struct PendingWrites<A: HalApi> {
     /// 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<TempResource<A>>,

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<T>` that holds those ids' referents:
 ///
-/// `IdentityManager` returns `Id`s whose index values are suitable for use as
-/// indices into a `Storage<T>` 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)>,

wgpu-core/src/pool.rs

@@ -26,9 +26,11 @@ impl<K: Clone + Eq + Hash, V> ResourcePool<K, V> {
         }
     }
 
-    /// 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<F, E>(&self, key: K, constructor: F) -> Result<Arc<V>, E>
     where
         F: FnOnce(K) -> Result<Arc<V>, E>,
@@ -96,6 +98,8 @@ impl<K: Clone + Eq + Hash, V> ResourcePool<K, V> {
     /// 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);
 

wgpu-core/src/registry.rs

@@ -98,9 +98,6 @@ impl<T: Resource> 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<T>) -> Id<T::Marker> {
         let mut data = self.data.write();
         debug_assert!(!data.contains(self.id));

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<A: HalApi> Tracker<A> {
     ///
     /// 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