Document random bits and pieces.

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(),
         });

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.