From a5e7275b9ca0124cf1fb01589309dcf297423bce Mon Sep 17 00:00:00 2001
From: Jim Blandy <jimb@red-bean.com>
Date: Tue, 10 May 2022 14:07:19 -0700
Subject: [PATCH] Document random bits and pieces.

---
 wgpu/examples/cube/main.rs | 11 +++++++++--
 wgpu/src/util/belt.rs      |  8 +++++---
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/wgpu/examples/cube/main.rs b/wgpu/examples/cube/main.rs
index b1d8c48931..bc180acb1b 100644
--- a/wgpu/examples/cube/main.rs
+++ b/wgpu/examples/cube/main.rs
@@ -83,8 +83,13 @@ fn create_texels(size: usize) -> Vec<u8> {
         .collect()
 }
 
-// This can be done simpler with `FutureExt`, but we don't want to add
-// a dependency just for this small case.
+/// A wrapper for `pop_error_scope` futures that panics if an error occurs.
+///
+/// Given a future `inner` of an `Option<E>` for some error type `E`,
+/// wait for the future to be ready, and panic if its value is `Some`.
+///
+/// This can be done simpler with `FutureExt`, but we don't want to add
+/// a dependency just for this small case.
 struct ErrorFuture<F> {
     inner: F,
 }
@@ -389,6 +394,8 @@ impl framework::Example for Example {
         }
 
         queue.submit(Some(encoder.finish()));
+
+        // If an error occurs, report it and panic.
         spawner.spawn_local(ErrorFuture {
             inner: device.pop_error_scope(),
         });
diff --git a/wgpu/src/util/belt.rs b/wgpu/src/util/belt.rs
index 6aa89c7a3e..efcbe7affa 100644
--- a/wgpu/src/util/belt.rs
+++ b/wgpu/src/util/belt.rs
@@ -48,14 +48,16 @@ struct Chunk {
 /// Staging belt is a machine that uploads data.
 ///
 /// Internally it uses a ring-buffer of staging buffers that are sub-allocated.
-/// It has an advantage over `Queue.write_buffer` in a way that it returns a mutable slice,
+/// It has an advantage over [`Queue::write_buffer`] in a way that it returns a mutable slice,
 /// which you can fill to avoid an extra data copy.
 ///
 /// Using a staging belt is slightly complicated, and generally goes as follows:
-/// - Write to buffers that need writing to using `write_buffer`.
+/// - Write to buffers that need writing to using [`StagingBelt::write_buffer`].
 /// - Call `finish`.
-/// - Submit all command encoders used with `write_buffer`.
+/// - Submit all command encoders used with `StagingBelt::write_buffer`.
 /// - Call `recall`
+///
+/// [`Queue::write_buffer`]: crate::Queue::write_buffer
 pub struct StagingBelt {
     chunk_size: BufferAddress,
     /// Chunks that we are actively using for pending transfers at this moment.