From 64777d4fd8120ee839bd2c149e86e93a65029fa2 Mon Sep 17 00:00:00 2001
From: Jim Blandy <jimb@red-bean.com>
Date: Wed, 1 May 2024 10:44:08 -0700
Subject: [PATCH] [core] Doc fixes for lifetime management, minor typos.

- Document `LifetimeTracker::triage_resources`.

- Fix various typos and bad grammar.
---
 wgpu-core/src/device/global.rs |  2 +-
 wgpu-core/src/device/life.rs   | 23 ++++++++++++++++++++++-
 wgpu-core/src/track/buffer.rs  |  4 ++--
 3 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/wgpu-core/src/device/global.rs b/wgpu-core/src/device/global.rs
index c1a5690d35..9ebecd80c7 100644
--- a/wgpu-core/src/device/global.rs
+++ b/wgpu-core/src/device/global.rs
@@ -2091,7 +2091,7 @@ impl Global {
     }
 
     #[cfg(feature = "replay")]
-    /// Only triangle suspected resource IDs. This helps us to avoid ID collisions
+    /// Only triage suspected resource IDs. This helps us to avoid ID collisions
     /// upon creating new resources when re-playing a trace.
     pub fn device_maintain_ids<A: HalApi>(&self, device_id: DeviceId) -> Result<(), InvalidDevice> {
         let hub = A::hub(self);
diff --git a/wgpu-core/src/device/life.rs b/wgpu-core/src/device/life.rs
index 0df580e6e6..c43087eaa6 100644
--- a/wgpu-core/src/device/life.rs
+++ b/wgpu-core/src/device/life.rs
@@ -468,6 +468,20 @@ impl<A: HalApi> LifetimeTracker<A> {
 }
 
 impl<A: HalApi> LifetimeTracker<A> {
+    /// Remove abandoned resources from `resources_map` and return them.
+    ///
+    /// Consult `trackers` to see which resources in `resources_map` are
+    /// abandoned (that is, referenced only by `resources_map` and `trackers`
+    /// itself) and remove them from `resources_map`.
+    ///
+    /// If the abandoned resources are in use by a command submission still in
+    /// flight, as listed in `active`, add them to that submission's
+    /// `ActiveSubmission::last_resources` map.
+    ///
+    /// Use `get_resource_map` to find the appropriate member of
+    /// `ActiveSubmission::last_resources` to hold resources of type `R`.
+    ///
+    /// Return a vector of all the abandoned resources that were removed.
     fn triage_resources<R>(
         resources_map: &mut FastHashMap<TrackerIndex, Arc<R>>,
         active: &mut [ActiveSubmission<A>],
@@ -584,6 +598,12 @@ impl<A: HalApi> LifetimeTracker<A> {
             &mut trackers.views,
             |maps| &mut maps.texture_views,
         );
+        // You might be tempted to add the view's parent texture to
+        // suspected_resources here, but don't. Texture views get dropped all
+        // the time, and once a texture is added to
+        // `LifetimeTracker::suspected_resources` it remains there until it's
+        // actually dropped, which for long-lived textures could be at the end
+        // of execution.
         self
     }
 
@@ -782,7 +802,8 @@ impl<A: HalApi> LifetimeTracker<A> {
     pub(crate) fn triage_suspected(&mut self, trackers: &Mutex<Tracker<A>>) {
         profiling::scope!("triage_suspected");
 
-        //NOTE: the order is important to release resources that depends between each other!
+        // NOTE: The order in which resource types are processed here is
+        // crucial. See "Entrained resources" in this function's doc comment.
         self.triage_suspected_render_bundles(trackers);
         self.triage_suspected_compute_pipelines(trackers);
         self.triage_suspected_render_pipelines(trackers);
diff --git a/wgpu-core/src/track/buffer.rs b/wgpu-core/src/track/buffer.rs
index 9a52a53253..d4b56c827f 100644
--- a/wgpu-core/src/track/buffer.rs
+++ b/wgpu-core/src/track/buffer.rs
@@ -303,8 +303,8 @@ impl<A: HalApi> ResourceTracker for BufferTracker<A> {
     ///
     /// A buffer is 'otherwise unused' when the only references to it are:
     ///
-    /// 1) the `Arc` that our caller, `LifetimeTracker::triage_suspected`, has just
-    ///    drained from `LifetimeTracker::suspected_resources`,
+    /// 1) the `Arc` that our caller, `LifetimeTracker::triage_resources`, is
+    ///    considering draining from `LifetimeTracker::suspected_resources`,
     ///
     /// 2) its `Arc` in [`self.metadata`] (owned by [`Device::trackers`]), and
     ///