Fixes and changes to the documentation for increasing clarity (#4806)

Co-authored-by: Connor Fitzgerald <connorwadefitzgerald@gmail.com>

README.md

@@ -8,9 +8,9 @@
 [![Build Status](https://github.com/gfx-rs/wgpu/workflows/CI/badge.svg)](https://github.com/gfx-rs/wgpu/actions)
 [![codecov.io](https://codecov.io/gh/gfx-rs/wgpu/branch/trunk/graph/badge.svg?token=84qJTesmeS)](https://codecov.io/gh/gfx-rs/wgpu)
 
-`wgpu` is a cross-platform, safe, pure-rust graphics api. It runs natively on Vulkan, Metal, D3D12, and OpenGL; and on top of WebGL2 and WebGPU on wasm.
+`wgpu` is a cross-platform, safe, pure-rust graphics API. It runs natively on Vulkan, Metal, D3D12, and OpenGL; and on top of WebGL2 and WebGPU on wasm.
 
-The api is based on the [WebGPU standard](https://gpuweb.github.io/gpuweb/). It serves as the core of the WebGPU integration in Firefox and Deno.
+The API is based on the [WebGPU standard](https://gpuweb.github.io/gpuweb/). It serves as the core of the WebGPU integration in Firefox and Deno.
 
 ## Repo Overview
 
@@ -26,7 +26,7 @@ The repository hosts the following libraries:
 
 The following binaries:
 
-- [![Crates.io](https://img.shields.io/crates/v/naga-cli.svg?label=naga-cli)](https://crates.io/crates/naga-cli) - Tool for translating shaders between different languages using naga.
+- [![Crates.io](https://img.shields.io/crates/v/naga-cli.svg?label=naga-cli)](https://crates.io/crates/naga-cli) - Tool for translating shaders between different languages using `naga`.
 - [![Crates.io](https://img.shields.io/crates/v/wgpu-info.svg?label=wgpu-info)](https://crates.io/crates/wgpu-info) - Tool for getting information on GPUs in the system.
 - `cts_runner` - WebGPU Conformance Test Suite runner using `deno_webgpu`.
 - `player` - standalone application for replaying the API traces.
@@ -39,9 +39,9 @@ For an overview of all the components in the gfx-rs ecosystem, see [the big pict
 
 Rust examples can be found at [wgpu/examples](examples). You can run the examples on native with `cargo run --bin wgpu-examples <example>`. See the [list of examples](examples).
 
-To run the examples on WebGPU on wasm, run `cargo xtask run-wasm --bin wgpu-example`. Then connect to `http://localhost:8000` in your WebGPU enabled browser, and you can choose an example to run.
+To run the examples on WebGPU on wasm, run `cargo xtask run-wasm --bin wgpu-example`. Then connect to `http://localhost:8000` in your WebGPU-enabled browser, and you can choose an example to run.
 
-To run the examples on WebGL on wasm, run `cargo xtask run-wasm --bin wgpu-example --features webgl`. Then connect to `http://localhost:8000` in your WebGL enabled browser, and you can choose an example to run.
+To run the examples on WebGL on wasm, run `cargo xtask run-wasm --bin wgpu-example --features webgl`. Then connect to `http://localhost:8000` in your WebGL-enabled browser, and you can choose an example to run.
 
 If you are looking for a wgpu tutorial, look at the following:
 
@@ -93,8 +93,7 @@ We have a [wiki](https://github.com/gfx-rs/wgpu/wiki) that serves as a knowledge
 
 wgpu supports shaders in [WGSL](https://gpuweb.github.io/gpuweb/wgsl/), SPIR-V, and GLSL.
 Both [HLSL](https://github.com/Microsoft/DirectXShaderCompiler) and [GLSL](https://github.com/KhronosGroup/glslang)
-have compilers to target SPIR-V. All of these shader languages can be used with any backend, we
-will handle all of the conversion. Additionally, support for these shader inputs is not going away.
+have compilers to target SPIR-V. All of these shader languages can be used with any backend as we handle all of the conversions. Additionally, support for these shader inputs is not going away.
 
 While WebGPU does not support any shading language other than WGSL, we will automatically convert your
 non-WGSL shaders if you're running on WebGPU.
@@ -110,9 +109,9 @@ To enable GLSL shaders, enable the `glsl` feature of wgpu.
 
 ### Angle
 
-[Angle](http://angleproject.org) is a translation layer from GLES to other backends, developed by Google.
+[Angle](http://angleproject.org) is a translation layer from GLES to other backends developed by Google.
 We support running our GLES3 backend over it in order to reach platforms DX11 support, which aren't accessible otherwise.
-In order to run with Angle, "angle" feature has to be enabled, and Angle libraries placed in a location visible to the application.
+In order to run with Angle, the "angle" feature has to be enabled, and Angle libraries placed in a location visible to the application.
 These binaries can be downloaded from [gfbuild-angle](https://github.com/DileSoft/gfbuild-angle) artifacts, [manual compilation](https://github.com/google/angle/blob/main/doc/DevSetup.md) may be required on Macs with Apple silicon.
 
 On Windows, you generally need to copy them into the working directory, in the same directory as the executable, or somewhere in your path.
@@ -122,10 +121,10 @@ On Linux, you can point to them using `LD_LIBRARY_PATH` environment.
 
 Due to complex dependants, we have two MSRV policies:
  - `d3d12`, `naga`, `wgpu-core`, `wgpu-hal`, and `wgpu-types`'s MSRV is **1.65**.
- - The rest of the workspace has the MSRV of **1.71**.
+ - The rest of the workspace has an MSRV of **1.71**.
 
-It is enforced on CI (in "/.github/workflows/ci.yml") with `CORE_MSRV` and `REPO_MSRV` variable.
-This version can only be upgraded in breaking releases, though we release a breaking version every 3 months.
+It is enforced on CI (in "/.github/workflows/ci.yml") with the `CORE_MSRV` and `REPO_MSRV` variables.
+This version can only be upgraded in breaking releases, though we release a breaking version every three months.
 
 The `naga`, `wgpu-core`, `wgpu-hal`, and `wgpu-types` crates should never
 require an MSRV ahead of Firefox's MSRV for nightly builds, as
@@ -136,10 +135,10 @@ determined by the value of `MINIMUM_RUST_VERSION` in
 
 ## Environment Variables
 
-All testing and example infrastructure shares the same set of environment variables that determine which Backend/GPU it will run on.
+All testing and example infrastructure share the same set of environment variables that determine which Backend/GPU it will run on.
 
 - `WGPU_ADAPTER_NAME` with a substring of the name of the adapter you want to use (ex. `1080` will match `NVIDIA GeForce 1080ti`).
-- `WGPU_BACKEND` with a comma separated list of the backends you want to use (`vulkan`, `metal`, `dx12`, `dx11`, or `gl`).
+- `WGPU_BACKEND` with a comma-separated list of the backends you want to use (`vulkan`, `metal`, `dx12`, `dx11`, or `gl`).
 - `WGPU_POWER_PREF` with the power preference to choose when a specific adapter name isn't specified (`high`, `low` or `none`)
 - `WGPU_DX12_COMPILER` with the DX12 shader compiler you wish to use (`dxc` or `fxc`, note that `dxc` requires `dxil.dll` and `dxcompiler.dll` to be in the working directory otherwise it will fall back to `fxc`)
 - `WGPU_GLES_MINOR_VERSION` with the minor OpenGL ES 3 version number to request (`0`, `1`, `2` or `automatic`).
@@ -187,7 +186,7 @@ If you are a user and want a way to help contribute to wgpu, we always need more
 
 WebGPU includes a Conformance Test Suite to validate that implementations are working correctly. We can run this CTS against wgpu.
 
-To run the CTS, first you need to check it out:
+To run the CTS, first, you need to check it out:
 
 ```
 git clone https://github.com/gpuweb/cts.git
@@ -199,7 +198,7 @@ git checkout $(cat ../cts_runner/revision.txt)
 To run a given set of tests:
 
 ```
-# Must be inside the cts folder we just checked out, else this will fail
+# Must be inside the `cts` folder we just checked out, else this will fail
 cargo run --manifest-path ../Cargo.toml --bin cts_runner -- ./tools/run_deno --verbose "<test string>"
 ```
 
@@ -224,7 +223,7 @@ Exactly which WGSL features `wgpu` supports depends on how you are using it:
   to translate WGSL code into the shading language of your platform's native GPU API.
   Naga has [a milestone][naga wgsl milestone]
   for catching up to the WGSL specification,
-  but in general there is no up-to-date summary
+  but in general, there is no up-to-date summary
   of the differences between Naga and the WGSL spec.
 
 - When running in a web browser (by compilation to WebAssembly)

deno_webgpu/README.md

@@ -19,7 +19,7 @@ running through our WPT runner. This will be used to validate implementation
 conformance.
 
 GitHub CI doesn't run with GPUs, so testing relies on software like DX WARP &
-Vulkan lavapipe. Currently only using DX WARP works, so tests are only run on
+Vulkan lavapipe. Currently, only using DX WARP works, so tests are only run on
 Windows.
 
 ## Links

examples/README.md

@@ -8,9 +8,9 @@ For the simplest examples without using any helping code (see `framework.rs` her
 
 ### Summary of examples
 
-A summary of the basic examples as split along the graphics and compute "pathways", layed out roughly in order of building on each other. Those further indented and thus more roughly dependant on more other examples tend to be more complicated as well as those further down. It should be noted though that computing examples, even though they are mentioned further down (because rendering to a window is by far the most common use case), tend to be less complex as they require less surrounding context to create and manage a window to render to.
+A summary of the basic examples as split along the graphics and compute "pathways" laid out roughly in order of building on each other. Those further indented, and thus more roughly dependent on more other examples, tend to be more complicated as well as those further down. It should be noted, though, that computing examples, even though they are mentioned further down (because rendering to a window is by far the most common use case), tend to be less complex as they require less surrounding context to create and manage a window to render to.
 
-The rest of the example are for demonstrating specific features that you can come back for later when you know what those features are.
+The rest of the examples are for demonstrating specific features that you can come back for later when you know what those features are.
 
 #### General
 
@@ -19,24 +19,24 @@ The rest of the example are for demonstrating specific features that you can com
 #### Graphics
 
 - `hello-triangle` - Provides an example of a bare-bones WGPU workflow using the Winit crate that simply renders a red triangle on a green background.
-- `uniform-values` - Demonstrates the basics of enabling shaders and the GPU in general to access app state through uniform variables. `uniform-values` also serves as an example of rudimentary app building as the app stores state and takes window-captured keyboard events. The app displays the Mandelbrot Set in grayscale (similar to `storage-texture`) but allows the user to navigate and explore it using their arrow keys and scroll wheel.
+- `uniform-values` - Demonstrates the basics of enabling shaders and the GPU, in general, to access app state through uniform variables. `uniform-values` also serves as an example of rudimentary app building as the app stores state and takes window-captured keyboard events. The app displays the Mandelbrot Set in grayscale (similar to `storage-texture`) but allows the user to navigate and explore it using their arrow keys and scroll wheel.
 - `cube` - Introduces the user to slightly more advanced models. The example creates a set of triangles to form a cube on the CPU and then uses a vertex and index buffer to send the generated model to the GPU for usage in rendering. It also uses a texture generated on the CPU to shade the sides of the cube and a uniform variable to apply a transformation matrix to the cube in the shader.
-- `bunnymark` - Demonstrates many things but chief among them, preforming numerous draw calls with different bind groups in one render pass. The example also uses textures for the icon and uniform buffers to transfer both global and per-particle state.
-- `skybox` - Shows off too many concepts to list here. The name comes from game development where a "skybox" acts as a background for rendering, usually to add a sky texture for immersion although they can also be used for backdrops to give the idea of a world beyond of the game scene. This example does so much more than this though as it uses a car model loaded from a file and uses the user's mouse to rotate the car model in 3d. `skybox` also makes use of depth textures and similar app patterns to `uniform-values`.
-- `shadow` - Likely by far the most complex example (certainly the largest in lines of code) of the official WGPU examples. `shadow` demonstrates basic scene rendering with the main attraction being lighting and shadows (as the name implies). It is recommended that any user looking into lighting be very familiar with the basic concepts of not only rendering with WGPU but the primary mathematical ideas of computer graphics.
+- `bunnymark` - Demonstrates many things, but chief among them is performing numerous draw calls with different bind groups in one render pass. The example also uses textures for the icon and uniform buffers to transfer both global and per-particle states.
+- `skybox` - Shows off too many concepts to list here. The name comes from game development where a "skybox" acts as a background for rendering, usually to add a sky texture for immersion, although they can also be used for backdrops to give the idea of a world beyond the game scene. This example does so much more than this, though, as it uses a car model loaded from a file and uses the user's mouse to rotate the car model in 3d. `skybox` also makes use of depth textures and similar app patterns to `uniform-values`.
+- `shadow` - Likely by far the most complex example (certainly the largest in lines of code) of the official WGPU examples. `shadow` demonstrates basic scene rendering with the main attraction being lighting and shadows (as the name implies). It is recommended that any user looking into lighting be very familiar with the basic concepts of not only rendering with WGPU but also the primary mathematical ideas of computer graphics.
 - `render-to-texture` - Renders to an image texture offscreen, demonstrating both off-screen rendering as well as how to add a sort of resolution-agnostic screenshot feature to an engine. This example either outputs an image file of your naming (pass command line arguments after specifying a `--` like `cargo run --bin render-to-texture -- "test.png"`) or adds an `img` element containing the image to the page in WASM.
 
 #### Compute
 
-- `hello-compute` - Demonstrates the basic workflow for getting arrays of numbers to the GPU, executing a shader on them, and getting the results back. The operation it preforms is finding the Collatz value (how many iterations of the [Collatz equation](https://en.wikipedia.org/wiki/Collatz_conjecture) it takes for the number to either reach 1 or overflow) of a set of numbers and prints the results.
-- `repeated-compute` - Mostly for going into detail on subjects `hello-compute` did not. It, too, computes the Collatz conjecture but this time, it automatically loads large arrays of randomly generated numbers, prints them, runs them, and prints the result. It does this cycle 10 times.
+- `hello-compute` - Demonstrates the basic workflow for getting arrays of numbers to the GPU, executing a shader on them, and getting the results back. The operation it performs is finding the Collatz value (how many iterations of the [Collatz equation](https://en.wikipedia.org/wiki/Collatz_conjecture) it takes for the number to either reach 1 or overflow) of a set of numbers and prints the results.
+- `repeated-compute` - Mostly for going into detail on subjects `hello-compute` did not. It, too, computes the Collatz conjecture, but this time, it automatically loads large arrays of randomly generated numbers, prints them, runs them, and prints the result. It does this cycle 10 times.
 - `hello-workgroups` - Teaches the user about the basics of compute workgroups; what they are and what they can do.
 - `hello-synchronization` - Teaches the user about synchronization in WGSL, the ability to force all invocations in a workgroup to synchronize with each other before continuing via a sort of barrier.
-- `storage-texture` - Demonstrates the use of storage textures as outputs to compute shaders. The example on the outside seems very similar to `render-to-texture` in that it outputs an image either to the file system or the web page except displaying a grayscale render of the Mandelbrot Set. However, inside, the example dispatches a grid of compute workgroups, one for each pixel which calculates the pixel value and stores it to the corresponding pixel of the output storage texture.
+- `storage-texture` - Demonstrates the use of storage textures as outputs to compute shaders. The example on the outside seems very similar to `render-to-texture` in that it outputs an image either to the file system or the web page, except displaying a grayscale render of the Mandelbrot Set. However, inside, the example dispatches a grid of compute workgroups, one for each pixel, which calculates the pixel value and stores it to the corresponding pixel of the output storage texture.
 
 #### Combined
 
-- `boids` - Demonstrates how to combine compute and render workflows by preforming a [boid](https://en.wikipedia.org/wiki/Boids) simulation and rendering the boids to the screen as little triangles.
+- `boids` - Demonstrates how to combine compute and render workflows by performing a [boid](https://en.wikipedia.org/wiki/Boids) simulation and rendering the boids to the screen as little triangles.
 
 ## Feature matrix
 
@@ -83,7 +83,7 @@ The rest of the example are for demonstrating specific features that you can com
 
 ## Additional notes
 
-Note that the examples regarding computing build off of each other; repeated-compute extends hello-compute, hello-workgroups assumes you know the basic workflow of gpu computation, and hello-synchronization assumes you know what a workgroup is. Also note that the computing examples cannot be downleveled to WebGL as WebGL does not allow storage textures. Running these in a browser will require that browser to support WebGPU.
+Note that the examples regarding computing build off of each other; repeated-compute extends hello-compute, hello-workgroups assumes you know the basic workflow of GPU computation, and hello-synchronization assumes you know what a workgroup is. Also, note that the computing examples cannot be downleveled to WebGL as WebGL does not allow storage textures. Running these in a browser will require that browser to support WebGPU.
 
 All the examples use [WGSL](https://gpuweb.github.io/gpuweb/wgsl.html) shaders unless specified otherwise.
 
@@ -91,8 +91,8 @@ All framework-based examples render to the window and are reftested against the
 
 ## Hacking
 
-You can record an API trace any of the framework-based examples by starting them as:
+You can record an API trace for any of the framework-based examples by starting them as:
 
 ```sh
-mkdir -p trace && WGPU_TRACE=trace cargo run --features trace --bin <example-name>
+mkdir -p trace && WGPU_TRACE=trace cargo run --features trace --bin wgpu-examples <example-name>
 ```

naga/README.md

@@ -33,7 +33,7 @@ DOT (GraphViz)  | :ok:               | dot-out  | Not a shading language |
 
 ## Conversion tool
 
-Naga can be used as a CLI, which allows to test the conversion of different code paths.
+Naga can be used as a CLI, which allows testing the conversion of different code paths.
 
 First, install `naga-cli` from crates.io or directly from GitHub.
 
@@ -54,7 +54,7 @@ naga my_shader.spv my_shader.metal --flow-dir flow-dir # convert the SPV to Meta
 naga my_shader.wgsl my_shader.vert --profile es310 # convert the WGSL to GLSL vertex stage under ES 3.20 profile
 ```
 
-As naga includes a default binary target, you can also use `cargo run` without installation. This is useful when you develop naga itself, or investigate the behavior of naga at a specific commit (e.g. [wgpu](https://github.com/gfx-rs/wgpu) might pin a different version of naga than the `HEAD` of this repository).
+As naga includes a default binary target, you can also use `cargo run` without installation. This is useful when you develop naga itself or investigate the behavior of naga at a specific commit (e.g. [wgpu](https://github.com/gfx-rs/wgpu) might pin a different version of naga than the `HEAD` of this repository).
 
 ```bash
 cargo run my_shader.wgsl
@@ -63,7 +63,7 @@ cargo run my_shader.wgsl
 ## Development workflow
 
 The main instrument aiding the development is the good old `cargo test --all-features --workspace`,
-which will run the unit tests, and also update all the snapshots. You'll see these
+which will run the unit tests and also update all the snapshots. You'll see these
 changes in git before committing the code.
 
 If working on a particular front-end or back-end, it may be convenient to
@@ -71,7 +71,7 @@ enable the relevant features in `Cargo.toml`, e.g.
 ```toml
 default = ["spv-out"] #TEMP!
 ```
-This allows IDE basic checks to report errors there, unless your IDE is sufficiently configurable already.
+This allows IDE basic checks to report errors there unless your IDE is sufficiently configurable already.
 
 Finally, when changes to the snapshots are made, we should verify that the produced shaders
 are indeed valid for the target platforms they are compiled for:

player/README.md

@@ -1,13 +1,13 @@
 # wgpu player
 
 This is an application that allows replaying the `wgpu` workloads recorded elsewhere. It requires the player to be built from
-the same revision as an application was linking to, or otherwise the data may fail to load.
+the same revision as an application was linking to, or otherwise, the data may fail to load.
 
 Launch as:
 ```rust
 play <trace-dir>
 ```
 
-When built with "winit" feature, it's able to replay the workloads that operate on a swapchain. It renders each frame sequentially, then waits for the user to close the window. When built without "winit", it launches in console mode and can replay any trace that doesn't use swapchains.
+When built with "winit" feature, it's able to replay the workloads that operate on a swapchain. It renders each frame sequentially and then waits for the user to close the window. When built without "winit", it launches in console mode and can replay any trace that doesn't use swapchains.
 
-Note: replaying is currently restricted to the same backend, as one used for recording a trace. It is straightforward, however, to just replace the backend in RON, since it's serialized as plain text. Valid values are: Vulkan, Metal, Dx12, and Dx11.
+Note: replaying is currently restricted to the same backend as one used for recording a trace. It is straightforward, however, to just replace the backend in RON since it's serialized as plain text. Valid values are: Vulkan, Metal, Dx12, and Dx11.

wgpu-hal/README.md

@@ -15,7 +15,7 @@ such as running out-of-memory, or losing the device.
 For the counter-example, there is no error for mapping a buffer that's not mappable.
 As the buffer creator, the user should already know if they can map it.
 
-The API accept iterators in order to avoid forcing the user to store data in particular containers. The implementation doesn't guarantee that any of the iterators are drained, unless stated otherwise by the function documentation.
+The API accepts iterators in order to avoid forcing the user to store data in particular containers. The implementation doesn't guarantee that any of the iterators are drained, unless stated otherwise by the function documentation.
 For this reason, we recommend that iterators don't do any mutating work.
 
 # Debugging

wgpu-info/README.md

@@ -14,6 +14,6 @@ cargo run --bin wgpu-info
 
 #### Running Test on many Adapters
 
-When called with any amount of arguments it will interpret all of the arguments as a command to run. It will run this command N different times, one for every combination of adapter and backend on the system.
+When called with any amount of arguments, it will interpret all of the arguments as a command to run. It will run this command N different times, one for every combination of adapter and backend on the system.
 
 For every command invocation, it will set `WGPU_ADAPTER_NAME` to the name of the adapter name and `WGPU_BACKEND` to the name of the backend. This is used as the primary means of testing across many adapters.

wgpu/src/lib.rs

@@ -3971,7 +3971,7 @@ impl<'a> RenderPass<'a> {
     /// This is like calling [`RenderPass::draw`] but the contents of the call are specified in the `indirect_buffer`.
     /// The structure expected in `indirect_buffer` must conform to [`DrawIndirectArgs`](crate::util::DrawIndirectArgs).
     ///
-    /// Indirect drawing has some caviats depending on the features available. We are not currently able to validate
+    /// Indirect drawing has some caveats depending on the features available. We are not currently able to validate
     /// these and issue an error.
     /// - If [`Features::INDIRECT_FIRST_INSTANCE`] is not present on the adapter,
     ///   [`DrawIndirect::first_instance`](crate::util::DrawIndirectArgs::first_instance) will be ignored.
@@ -3996,7 +3996,7 @@ impl<'a> RenderPass<'a> {
     /// This is like calling [`RenderPass::draw_indexed`] but the contents of the call are specified in the `indirect_buffer`.
     /// The structure expected in `indirect_buffer` must conform to [`DrawIndexedIndirectArgs`](crate::util::DrawIndexedIndirectArgs).
     ///
-    /// Indirect drawing has some caviats depending on the features available. We are not currently able to validate
+    /// Indirect drawing has some caveats depending on the features available. We are not currently able to validate
     /// these and issue an error.
     /// - If [`Features::INDIRECT_FIRST_INSTANCE`] is not present on the adapter,
     ///   [`DrawIndexedIndirect::first_instance`](crate::util::DrawIndexedIndirectArgs::first_instance) will be ignored.