Format all Markdown files with dprint (#1157)

This is the result of running `dprint fmt` after removing `src/` from
the list of excluded directories.

This also reformats the Rust code: we might want to tweak this a bit in
the future since some of the changes removes the hand-formatting. Of
course, this formatting can be seen as a mis-feature, so maybe this is
good overall.

Thanks to mdbook-i18n-helpers 0.2, the POT file is nearly unchanged
after this, meaning that all existing translations remain valid! A few
messages were changed because of stray whitespace characters:

     msgid ""
     "Slices always borrow from another object. In this example, `a` has to remain "
    -"'alive' (in scope) for at least as long as our slice. "
    +"'alive' (in scope) for at least as long as our slice."
     msgstr ""

The formatting is enforced in CI and we will have to see how annoying
this is in practice for the many contributors. If it becomes annoying,
we should look into fixing dprint/check#11 so that `dprint` can annotate
the lines that need fixing directly, then I think we can consider more
strict formatting checks.

I added more customization to `rustfmt.toml`. This is to better emulate
the dense style used in the course:

- `max_width = 85` allows lines to take up the full width available in
our code blocks (when taking margins and the line numbers into account).
- `wrap_comments = true` ensures that we don't show very long comments
in the code examples. I edited some comments to shorten them and avoid
unnecessary line breaks — please trim other unnecessarily long comments
when you see them! Remember we're writing code for slides 😄
- `use_small_heuristics = "Max"` allows for things like struct literals
and if-statements to take up the full line width configured above.

The formatting settings apply to all our Rust code right now — I think
we could improve this with https://github.com/dprint/dprint/issues/711
which lets us add per-directory `dprint` configuration files. However,
the `inherit: true` setting is not yet implemented (as far as I can
tell), so a nested configuration file will have to copy most or all of
the top-level file.

src/unsafe-rust/dereferencing.md

@@ -35,19 +35,20 @@ fn main() {
 
 <details>
 
-It is good practice (and required by the Android Rust style guide) to write a comment for each
-`unsafe` block explaining how the code inside it satisfies the safety requirements of the unsafe
-operations it is doing.
+It is good practice (and required by the Android Rust style guide) to write a
+comment for each `unsafe` block explaining how the code inside it satisfies the
+safety requirements of the unsafe operations it is doing.
 
 In the case of pointer dereferences, this means that the pointers must be
 [_valid_](https://doc.rust-lang.org/std/ptr/index.html#safety), i.e.:
 
- * The pointer must be non-null.
- * The pointer must be _dereferenceable_ (within the bounds of a single allocated object).
- * The object must not have been deallocated.
- * There must not be concurrent accesses to the same location.
- * If the pointer was obtained by casting a reference, the underlying object must be live and no
-   reference may be used to access the memory.
+- The pointer must be non-null.
+- The pointer must be _dereferenceable_ (within the bounds of a single allocated
+  object).
+- The object must not have been deallocated.
+- There must not be concurrent accesses to the same location.
+- If the pointer was obtained by casting a reference, the underlying object must
+  be live and no reference may be used to access the memory.
 
 In most cases the pointer must also be properly aligned.
 

src/unsafe-rust/exercise.md

@@ -10,15 +10,15 @@ functions you would use from C to read the names of files in a directory.
 
 You will want to consult the manual pages:
 
-* [`opendir(3)`](https://man7.org/linux/man-pages/man3/opendir.3.html)
-* [`readdir(3)`](https://man7.org/linux/man-pages/man3/readdir.3.html)
-* [`closedir(3)`](https://man7.org/linux/man-pages/man3/closedir.3.html)
+- [`opendir(3)`](https://man7.org/linux/man-pages/man3/opendir.3.html)
+- [`readdir(3)`](https://man7.org/linux/man-pages/man3/readdir.3.html)
+- [`closedir(3)`](https://man7.org/linux/man-pages/man3/closedir.3.html)
 
 You will also want to browse the [`std::ffi`] module. There you find a number of
 string types which you need for the exercise:
 
 | Types                      | Encoding       | Use                            |
-|----------------------------|----------------|--------------------------------|
+| -------------------------- | -------------- | ------------------------------ |
 | [`str`] and [`String`]     | UTF-8          | Text processing in Rust        |
 | [`CStr`] and [`CString`]   | NUL-terminated | Communicating with C functions |
 | [`OsStr`] and [`OsString`] | OS-specific    | Communicating with the OS      |
@@ -27,13 +27,15 @@ You will convert between all these types:
 
 - `&str` to `CString`: you need to allocate space for a trailing `\0` character,
 - `CString` to `*const i8`: you need a pointer to call C functions,
-- `*const i8` to `&CStr`: you need something which can find the trailing `\0` character,
-- `&CStr` to `&[u8]`: a slice of bytes is the universal interface for "some unknown data",
+- `*const i8` to `&CStr`: you need something which can find the trailing `\0`
+  character,
+- `&CStr` to `&[u8]`: a slice of bytes is the universal interface for "some
+  unknown data",
 - `&[u8]` to `&OsStr`: `&OsStr` is a step towards `OsString`, use
-  [`OsStrExt`](https://doc.rust-lang.org/std/os/unix/ffi/trait.OsStrExt.html)
-  to create it,
-- `&OsStr` to `OsString`: you need to clone the data in `&OsStr` to be able to return it and call
-  `readdir` again.
+  [`OsStrExt`](https://doc.rust-lang.org/std/os/unix/ffi/trait.OsStrExt.html) to
+  create it,
+- `&OsStr` to `OsString`: you need to clone the data in `&OsStr` to be able to
+  return it and call `readdir` again.
 
 The [Nomicon] also has a very useful chapter about FFI.
 

src/unsafe-rust/exercise.rs

@@ -86,7 +86,8 @@ impl DirectoryIterator {
         // Call opendir and return a Ok value if that worked,
         // otherwise return Err with a message.
         // ANCHOR_END: DirectoryIterator
-        let path = CString::new(path).map_err(|err| format!("Invalid path: {err}"))?;
+        let path =
+            CString::new(path).map_err(|err| format!("Invalid path: {err}"))?;
         // SAFETY: path.as_ptr() cannot be NULL.
         let dir = unsafe { ffi::opendir(path.as_ptr()) };
         if dir.is_null() {

src/unsafe-rust/mutable-static.md

@@ -21,23 +21,29 @@ static variables:
 static mut COUNTER: u32 = 0;
 
 fn add_to_counter(inc: u32) {
-    unsafe { COUNTER += inc; }  // Potential data race!
+    unsafe {
+        COUNTER += inc;
+    }
 }
 
 fn main() {
     add_to_counter(42);
 
-    unsafe { println!("COUNTER: {COUNTER}"); }  // Potential data race!
+    unsafe {
+        println!("COUNTER: {COUNTER}");
+    }
 }
 ```
 
 <details>
 
-- The program here is safe because it is single-threaded. However, the Rust compiler is conservative
-  and will assume the worst. Try removing the `unsafe` and see how the compiler explains that it is
-  undefined behavior to mutate a static from multiple threads.
+- The program here is safe because it is single-threaded. However, the Rust
+  compiler is conservative and will assume the worst. Try removing the `unsafe`
+  and see how the compiler explains that it is undefined behavior to mutate a
+  static from multiple threads.
 
-- Using a mutable static is generally a bad idea, but there are some cases where it might make sense
-  in low-level `no_std` code, such as implementing a heap allocator or working with some C APIs.
+- Using a mutable static is generally a bad idea, but there are some cases where
+  it might make sense in low-level `no_std` code, such as implementing a heap
+  allocator or working with some C APIs.
 
 </details>

src/unsafe-rust/unions.md

@@ -16,17 +16,18 @@ union MyUnion {
 fn main() {
     let u = MyUnion { i: 42 };
     println!("int: {}", unsafe { u.i });
-    println!("bool: {}", unsafe { u.b });  // Undefined behavior!
+    println!("bool: {}", unsafe { u.b }); // Undefined behavior!
 }
 ```
 
 <details>
 
-Unions are very rarely needed in Rust as you can usually use an enum. They are occasionally needed
-for interacting with C library APIs.
+Unions are very rarely needed in Rust as you can usually use an enum. They are
+occasionally needed for interacting with C library APIs.
 
 If you just want to reinterpret bytes as a different type, you probably want
-[`std::mem::transmute`](https://doc.rust-lang.org/stable/std/mem/fn.transmute.html) or a safe
-wrapper such as the [`zerocopy`](https://crates.io/crates/zerocopy) crate.
+[`std::mem::transmute`](https://doc.rust-lang.org/stable/std/mem/fn.transmute.html)
+or a safe wrapper such as the [`zerocopy`](https://crates.io/crates/zerocopy)
+crate.
 
 </details>

src/unsafe-rust/unsafe-functions.md

@@ -34,7 +34,8 @@ fn main() {
 
     // Not upholding the UTF-8 encoding requirement breaks memory safety!
     // println!("emoji: {}", unsafe { emojis.get_unchecked(0..3) });
-    // println!("char count: {}", count_chars(unsafe { emojis.get_unchecked(0..3) }));
+    // println!("char count: {}", count_chars(unsafe {
+    // emojis.get_unchecked(0..3) }));
 }
 
 fn count_chars(s: &str) -> usize {
@@ -44,8 +45,8 @@ fn count_chars(s: &str) -> usize {
 
 ## Writing Unsafe Functions
 
-You can mark your own functions as `unsafe` if they require particular conditions to avoid undefined
-behaviour.
+You can mark your own functions as `unsafe` if they require particular
+conditions to avoid undefined behaviour.
 
 ```rust,editable
 /// Swaps the values pointed to by the given pointers.
@@ -78,10 +79,10 @@ fn main() {
 
 `get_unchecked`, like most `_unchecked` functions, is unsafe, because it can
 create UB if the range is incorrect. `abs` is incorrect for a different reason:
-it is an external function (FFI).  Calling external functions is usually only a
+it is an external function (FFI). Calling external functions is usually only a
 problem when those functions do things with pointers which might violate Rust's
-memory model, but in general any C function might have undefined behaviour
-under any arbitrary circumstances.
+memory model, but in general any C function might have undefined behaviour under
+any arbitrary circumstances.
 
 The `"C"` in this example is the ABI;
 [other ABIs are available too](https://doc.rust-lang.org/reference/items/external-blocks.html).

src/unsafe-rust/unsafe-traits.md

@@ -4,8 +4,8 @@ minutes: 5
 
 # Implementing Unsafe Traits
 
-Like with functions, you can mark a trait as `unsafe` if the implementation must guarantee
-particular conditions to avoid undefined behaviour.
+Like with functions, you can mark a trait as `unsafe` if the implementation must
+guarantee particular conditions to avoid undefined behaviour.
 
 For example, the `zerocopy` crate has an unsafe trait that looks
 [something like this](https://docs.rs/zerocopy/latest/zerocopy/trait.AsBytes.html):
@@ -20,7 +20,10 @@ use std::slice;
 pub unsafe trait AsBytes {
     fn as_bytes(&self) -> &[u8] {
         unsafe {
-            slice::from_raw_parts(self as *const Self as *const u8, size_of_val(self))
+            slice::from_raw_parts(
+                self as *const Self as *const u8,
+                size_of_val(self),
+            )
         }
     }
 }
@@ -31,8 +34,8 @@ unsafe impl AsBytes for u32 {}
 
 <details>
 
-There should be a `# Safety` section on the Rustdoc for the trait explaining the requirements for
-the trait to be safely implemented.
+There should be a `# Safety` section on the Rustdoc for the trait explaining the
+requirements for the trait to be safely implemented.
 
 The actual safety section for `AsBytes` is rather longer and more complicated.
 

src/unsafe-rust/unsafe.md

@@ -6,22 +6,22 @@ minutes: 5
 
 The Rust language has two parts:
 
-* **Safe Rust:** memory safe, no undefined behavior possible.
-* **Unsafe Rust:** can trigger undefined behavior if preconditions are violated.
+- **Safe Rust:** memory safe, no undefined behavior possible.
+- **Unsafe Rust:** can trigger undefined behavior if preconditions are violated.
 
-We saw mostly safe Rust in this course, but it's important to know
-what Unsafe Rust is.
+We saw mostly safe Rust in this course, but it's important to know what Unsafe
+Rust is.
 
-Unsafe code is usually small and isolated, and its correctness should be carefully
-documented. It is usually wrapped in a safe abstraction layer.
+Unsafe code is usually small and isolated, and its correctness should be
+carefully documented. It is usually wrapped in a safe abstraction layer.
 
 Unsafe Rust gives you access to five new capabilities:
 
-* Dereference raw pointers.
-* Access or modify mutable static variables.
-* Access `union` fields.
-* Call `unsafe` functions, including `extern` functions.
-* Implement `unsafe` traits.
+- Dereference raw pointers.
+- Access or modify mutable static variables.
+- Access `union` fields.
+- Call `unsafe` functions, including `extern` functions.
+- Implement `unsafe` traits.
 
 We will briefly cover unsafe capabilities next. For full details, please see
 [Chapter 19.1 in the Rust Book](https://doc.rust-lang.org/book/ch19-01-unsafe-rust.html)