More doc updates

Author: andyleiserson

wgpu-core/src/device/queue.rs

@@ -642,8 +642,14 @@ impl WebGpuError for QueueSubmitError {
 ///    surface textures they reference in [`surface_textures`]. Contribute to
 ///    [`Queue::pending_writes`] as necessary.
 ///
-/// 3) Call the `PendingSubmission`'s [`submit`] method, passing your mutex
-///    guard on [`Queue::pending_writes`].
+/// 3) Acquire the pending writes lock. This may be done at any point between
+///    the return from [`Queue::allocate_submission`] and the call to
+///    [`submit`]. Typically it should be done as late as is possible given
+///    any necessary pending writes activity.
+///
+/// 4) Call the `PendingSubmission`'s [`submit`] method (which is a convenience
+///    wrapper around [`Queue::submit_pending_submission`]). Pass the pending
+///    writes mutex guard to [`submit`].
 ///
 /// It is also acceptable to drop the `PendingSubmission` without submitting;
 /// this frees its locks in the appropriate order. This may be necessary when
@@ -657,7 +663,7 @@ impl WebGpuError for QueueSubmitError {
 /// - [`Queue::submit`] just submits user-constructed [`CommandBuffer`]s.
 ///
 /// - [`Queue::prepare_surface_texture_for_present`] examines the surface
-///   texture being presented, and submit deferred initialization commands and
+///   texture being presented, and submits deferred initialization commands and
 ///   barriers to get it ready.
 ///
 /// - [`Queue::flush_writes_for_buffer`] and [`Queue::flush_pending_writes`]
@@ -693,7 +699,7 @@ pub(crate) struct PendingSubmission<'a> {
 
     /// Surface textures referenced by command buffers in this submission.
     ///
-    /// These need to be passed to the [`wgpu_hal::Queue::submit`], which
+    /// These need to be passed to [`wgpu_hal::Queue::submit`], which
     /// requires that the list contains no duplicates, so we store them in a
     /// `HashMap` keyed by `SurfaceTexture` address.
     surface_textures: FastHashMap<*const Texture, Arc<Texture>>,
@@ -1697,7 +1703,7 @@ impl Queue {
     /// Returns the index and a [`PendingSubmission`].
     ///
     /// The caller passes in the already-acquired [`SnatchGuard`]. This function acquires
-    /// the fence lock and the command index lock.
+    /// the command index lock.
     ///
     /// The caller should update [`PendingSubmission::executions`] with details of the
     /// submission.

wgpu-core/src/device/resource.rs

@@ -710,9 +710,11 @@ impl Device {
     /// Note that a `false` result here does *not* guarantee that no further activity will
     /// occur on the `Device`. A [`Device`] can be marked invalid at any time, even while
     /// locks are held, meaning that operations begun before the `Device` was marked
-    /// invalid will still generally run to completion. This is simply a consequence of
-    /// making [`Device::valid`] an `AtomicBool`, rather than an ordinary `bool` field
-    /// protected by the same locks that all other operations acquire.
+    /// invalid will still generally run to completion. This is a consequence of
+    /// making [`Device::valid`] an `AtomicBool`. It could be avoided by making
+    /// [`Device::valid`] an ordinary `bool` field protected by the same locks that
+    /// all other operations acquire, but we use an `AtomicBool` because there
+    /// are many device validity checks and we want those to be cheap.
     pub fn is_valid(&self) -> bool {
         self.valid.load(Ordering::Acquire)
     }
@@ -972,7 +974,7 @@ impl Device {
         // However, checking device validity for this purpose is tricky. A device can be
         // marked invalid at any time, regardless of what locks are held. This means that,
         // even though queue submission does check device validity at the start (in
-        // `Queue::allocate_submission`), the submission will proceed even if the the
+        // `Queue::allocate_submission`), the submission will proceed even if the
         // device gets marked invalid after that check. Thus, other threads can observe
         // the queue becoming non-empty even after they have observed the device to be
         // invalid.