rust: improve docs

Co-authored-by: cole-h <cole.e.helbling@outlook.com>
Co-authored-by: asymmetric <lorenzo@mailbox.org>

1 files changed, 27 insertions, 27 deletions

diff --git a/doc/languages-frameworks/rust.section.md b/doc/languages-frameworks/rust.section.md
index 066633b53c4..7e5cff8ff60 100644
--- a/doc/languages-frameworks/rust.section.md
+++ b/doc/languages-frameworks/rust.section.md
@@ -79,11 +79,12 @@ pkgs.rustPlatform.buildRustPackage {
 
 When using `buildRustPackage`, the `checkPhase` is enabled by default and runs
 `cargo test` on the package to build. To make sure that we don't compile the
-sources twice and to actually test the artifacts that will be used after that, 
-the tests will be ran in the `release`-mode by default.
+sources twice and to actually test the artifacts that will be used at runtime, 
+the tests will be ran in the `release` mode by default.
 
 However, in some cases the test-suite of a package doesn't work properly in the
-`release` mode. In that case, the mode for `checkPhase` can be changed like this:
+`release` mode. For these situations, the mode for `checkPhase` can be changed like
+so:
 
 ```nix
 rustPlatform.buildRustPackage {
@@ -92,37 +93,37 @@ rustPlatform.buildRustPackage {
 }
 ```
 
-#### Tests relying on the structure of the `target/`-directory
+Please note that the code will be compiled twice here: once in `release` mode
+for the `buildPhase`, and again in `debug` mode for the `checkPhase`.
 
-Some tests may rely on the structure of the `target/`-directory. Those tests
-are likely to fail since we use `cargo --target` during build. This means that
+#### Tests relying on the structure of the `target/` directory
+
+Some tests may rely on the structure of the `target/` directory. Those tests
+are likely to fail because we use `cargo --target` during the build. This means that
 the artifacts
-[are stored in `target/<architecture>/release/`](https://doc.rust-lang.org/cargo/guide/build-cache.html)
-rather than `target/release/`.
+[are stored in `target/<architecture>/release/`](https://doc.rust-lang.org/cargo/guide/build-cache.html),
+rather than in `target/release/`.
 
-This can only be circumvented by patching the affected tests accordingly.
+This can only be worked around by patching the affected tests accordingly.
 
 #### Disabling package-tests
 
-In some cases it's necessary to disable the tests (which can be done by declaring
-`doCheck = false;`) which is fine in the following cases:
-
-* If no tests exist, the `checkPhase` should be explicitly disabled to skip
-  unnecessary build-steps to speed-up the build.
+In some instances, it may be necessary to disable testing altogether (with `doCheck = false;`):
 
-* If tests are highly impure (e.g. due to heavy network usage), it's also fine
-  disable tests.
+* If no tests exist -- the `checkPhase` should be explicitly disabled to skip
+  unnecessary build steps to speed up the build.
+* If tests are highly impure (e.g. due to network usage).
 
-There are obviously some other corner-cases where it's sensible to disable tests,
-those aren't hard-rules, in the end this is a case-by-case decision.
+There will obviously be some corner-cases not listed above where it's sensible to disable tests.
+The above are just guidelines, and exceptions may be granted on a case-by-case basis.
 
-Please check however if it's possible to disable a problematic subset of the
-test-suite and leave comment which explains why that's needed.
+However, please check if it's possible to disable a problematic subset of the
+test suite and leave a comment explaining your reasoning.
 
-### Building a package in the `debug` mode
+### Building a package in `debug` mode
 
-By default, `buildRustPackage` will use the `release`-mode for building. If a package
-should be built in the `debug`-mode however, it can be configured like this:
+By default, `buildRustPackage` will use `release` mode for builds. If a package
+should be built in `debug` mode, it can be configured like so:
 
 ```nix
 rustPlatform.buildRustPackage {
@@ -131,15 +132,14 @@ rustPlatform.buildRustPackage {
 }
 ```
 
-Obviously, the `checkPhase` will be ran in `debug`-mode as well in this case.
+In this scenario, the `checkPhase` will be ran in `debug` mode as well.
 
 ### Custom `build`/`install`-procedures
 
 Some packages may use custom scripts for building/installing, e.g. with a `Makefile`.
-In that case it's recommended to always override the `build-`/`install-`/`checkPhase`.
+In these cases, it's recommended to override the `buildPhase`/`installPhase`/`checkPhase`.
 
-Otherwise, it may be possible that one of the internal steps fails because of the
-modified directory structure of `target/`.
+Otherwise, some steps may fail because of the modified directory structure of `target/`.
 
 ## Compiling Rust crates using Nix instead of Cargo