improve the raii chapter slides based on the new STYLE guidelines

Author: GlenDC

src/idiomatic/leveraging-the-type-system/raii.md

@@ -40,9 +40,7 @@ fn main() -> Result<(), std::io::Error> {
 
 <details>
 
-- This example shows how easy it is to forget releasing a file descriptor when
-  managing it manually. The code as written does not call `file.close()`. Did
-  anyone in the class notice?
+- Easy to miss: `file.close()` is never called. Ask the class if they noticed.
 
 - To release the file descriptor correctly, `file.close()` must be called after
   the last use — and also in early-return paths in case of errors.
@@ -60,8 +58,8 @@ fn main() -> Result<(), std::io::Error> {
   ```
 
 - Note that `Drop::drop` cannot return errors. Any fallible logic must be
-  handled internally or ignored. In the standard library, errors returned while
-  closing an owned file descriptor during `Drop` are silently discarded:
+  handled internally or ignored. In the standard library, errors during FD
+  closure inside `Drop` are silently discarded. See the implementation:
   <https://doc.rust-lang.org/src/std/os/fd/owned.rs.html#169-196>
 
 - When is `Drop::drop` called?
@@ -75,8 +73,8 @@ fn main() -> Result<(), std::io::Error> {
   In contrast, C++ runs destructors in the original scope even for moved-from
   values.
 
-- Insert `panic!("oops")` at the start of `read_to_end()` to show that `drop()`
-  still runs during unwinding.
+- Demo: insert `panic!("oops")` at the start of `read_to_end()` and run it.
+  `drop()` still runs during unwinding.
 
 ### More to Explore
 

src/idiomatic/leveraging-the-type-system/raii/drop_bomb.md

@@ -45,28 +45,30 @@ fn main() -> io::Result<()> {
 <details>
 
 - A drop bomb ensures that a value like `Transaction` cannot be silently dropped
-  in an unfinished state. The destructor panics if neither `commit()` nor
-  `rollback()` has been called.
+  in an unfinished state. The destructor panics if the transaction has not been
+  explicitly finalized (for example, with `commit()`).
 
-- The finalizing operation (like `commit()` or `rollback()`) often consumes the
-  object and thus prevents the user from handling a finalized object.
+- The finalizing operation (such as `commit()`) usually take `self` by value.
+  This ensures that once the transaction is finalized, the original object can
+  no longer be used.
 
 - A common reason to use this pattern is when cleanup cannot be done in `Drop`,
   either because it is fallible or asynchronous.
 
 - This pattern is appropriate even in public APIs. It can help users catch bugs
   early when they forget to explicitly finalize a transactional object.
 
-- If a value can be safely cleaned up in `Drop`, consider falling back to that
-  behavior in Release mode and panicking only in Debug. This decision should be
-  made based on the guarantees your API provides.
+- If cleanup can safely happen in `Drop`, some APIs choose to panic only in
+  debug builds. Whether this is appropriate depends on the guarantees your API
+  must enforce.
 
-- Panicking in Release builds is a valid choice if silent misuse could lead to
-  serious correctness issues or security concerns.
+- Panicking in Release builds is reasonable when silent misuse would cause major
+  correctness or security problems.
 
 ## More to explore
 
-There are additional patterns related to this slide that could be explored.
+Several related patterns help enforce correct teardown or prevent accidental
+drops.
 
 - The [`drop_bomb` crate](https://docs.rs/drop_bomb/latest/drop_bomb/): A small
   utility that panics if dropped unless explicitly defused with `.defuse()`.

src/idiomatic/leveraging-the-type-system/raii/drop_bomb_forget.md

@@ -42,8 +42,12 @@ In the previous slide we saw that calling
 [`std::mem::forget`](https://doc.rust-lang.org/std/mem/fn.forget.html) prevents
 `Drop::drop` from ever running.
 
-This lets us avoid using a runtime flag entirely: when the transaction is
-successfully committed, we can defuse the drop bomb by forgetting the value
-instead of letting its destructor run.
+Remember that `mem::forget` leaks the value. This is safe in Rust, but the
+memory will not be reclaimed.
+
+However, this avoids needing a runtime flag: when the transaction is
+successfully committed, we can _defuse_ the drop bomb — meaning we prevent
+`Drop` from running — by calling `std::mem::forget` on the value instead of
+letting its destructor run.
 
 </details>

src/idiomatic/leveraging-the-type-system/raii/drop_guards.md

@@ -33,11 +33,13 @@ impl Drop for MutexGuard<'_> {
 
 <details>
 
-- The example above shows a simplified `Mutex` and its associated guard. Even
-  though it is not a production-ready implementation, it illustrates the core
-  idea: the guard enforces exclusive access, and its `Drop` implementation is
-  used to unlock it again when the guard goes out of scope or is manually
-  dropped.
+- The example above shows a simplified `Mutex` and its associated guard.
+
+- Even though it is not a production-ready implementation, it illustrates the
+  core idea:
+
+  - the guard represents exclusive access,
+  - and its `Drop` implementation releases the lock when it goes out of scope.
 
 ## More to Explore
 
@@ -47,14 +49,16 @@ core idea of a drop guard, not to demonstrate a proper Rust mutex design.
 
 For brevity, several features are omitted:
 
-- Unlike the std `Mutex`, which owns its value, this version keeps the value
-  next to the `Mutex` rather than inside it.
-- Ergonomic access via `Deref` and `DerefMut` on `MutexGuard`.
+- A real `Mutex<T>` stores the protected value inside the mutex.\
+  This toy example omits the value entirely to focus only on the drop guard
+  mechanism.
+- Ergonomic access via `Deref` and `DerefMut` on `MutexGuard` (letting the guard
+  behave like a `&T` or `&mut T`).
 - A fully blocking `.lock()` method and a non blocking `try_lock` variant.
 
 You can explore the
 [`Mutex` implementation in Rust’s std library](https://doc.rust-lang.org/std/sync/struct.Mutex.html)
-as an example of a production ready mutex. The
+as an example of a production-ready mutex. The
 [`Mutex` from the `parking_lot` crate](https://docs.rs/parking_lot/latest/parking_lot/type.Mutex.html)
 is another worthwhile reference.
 

src/idiomatic/leveraging-the-type-system/raii/drop_option.md

@@ -54,31 +54,31 @@ fn main() -> std::io::Result<()> {
 - At the same time we still want RAII semantics: if the user forgets to call
   `close()`, the handle must be cleaned up automatically in `Drop`.
 
-- Wrapping the handle in an `Option` gives us both behaviors.\
-  `close()` extracts the handle with `take()`, and `Drop` only runs cleanup if a
-  handle is still present.
-  
-  You can demonstrate this by removing the line where we call `.close()`.
+- Wrapping the handle in an `Option` gives us both behaviors. `close()` extracts
+  the handle with `take()`, and `Drop` only runs cleanup if a handle is still
+  present.
+
+  Demo: remove the `.close()` call and run the code — `Drop` now prints the
+  automatic cleanup.
 
 - The main downside is ergonomics. `Option` forces us to handle both the `Some`
-  and `None` case even in places where, logically, `None` should be impossible.
-  Rust’s type system cannot express that guarantee here, so we pay a small
-  boilerplate cost.
+  and `None` case even in places where, logically, `None` cannot occur. Rust’s
+  type system cannot express that relationship between `File` and its `Handle`,
+  so we handle both cases manually.
 
 ## More to explore
 
 Instead of `Option` we could use
 [`ManuallyDrop`](https://doc.rust-lang.org/std/mem/struct.ManuallyDrop.html),
-which suppresses automatic destruction and gives full manual control.\
-This approach requires `unsafe`, since `ManuallyDrop` provides no guarantees
-that the programmer uses it correctly.
+which suppresses automatic destruction by preventing Rust from calling `Drop`
+for the value; you must handle teardown yourself.
 
 The [_scopeguard_ example](./scope_guard.md) on the previous slide shows how
 `ManuallyDrop` can replace `Option` to avoid handling `None` in places where the
 value should always exist.
 
 In such designs we typically track the drop state with a separate flag next to
-the `ManuallyDrop<Handle>`, allowing us to express whether the handle has
-already been manually consumed.
+the `ManuallyDrop<Handle>`, which lets us track whether the handle has already
+been manually consumed.
 
 </details>

src/idiomatic/leveraging-the-type-system/raii/drop_skipped.md

@@ -45,28 +45,25 @@ fn main() {
   [`std::mem::forget`](https://doc.rust-lang.org/std/mem/fn.forget.html) call.
   What do you think will happen?
 
-  Forgetting a value intentionally _leaks_ it. Leaking is still memory safe, but
-  it prevents the destructor from ever running, so `drop()` will _not_ be
-  called.
+  Forgetting a value intentionally _leaks_ it — the memory is never reclaimed,
+  but this is still memory-safe in Rust. Since the value is never dropped, its
+  destructor does not run.
 
   [`Box::leak`](https://doc.rust-lang.org/std/boxed/struct.Box.html#method.leak)
   is another example of intentional leaking, often used to create data that
   lives for the remainder of the process.
 
-- Undo the leak and uncomment the `panic!` just below it. What do you expect
-  now?
+- Remove the `mem::forget` call, then uncomment the `panic!` below it. What do
+  you expect now?
 
-  The stack will still unwind and the destructors will still run, even when the
-  panic originates in `main`.
+  With the default `panic=unwind` setting, the stack still unwinds and
+  destructors run, even when the panic starts in `main`.
 
-  - This is only true when compiling with the default `panic=unwind` config
-    profile.
-
-    With
+  - With
     [`panic=abort`](https://doc.rust-lang.org/cargo/reference/profiles.html#panic),
     no unwinding takes place.
 
-- Finally, consider what happens when you also uncomment the `panic!` inside
-  `Foo::drop`.
+- Finally, uncomment the `panic!` inside `Foo::drop` and run it. Ask the class:
+  which destructors run before the abort?
 
 </details>

src/idiomatic/leveraging-the-type-system/raii/mutex.md

@@ -21,21 +21,20 @@ fn main() {
 <details>
 
 - A `Mutex` controls exclusive access to a value. Unlike earlier RAII examples,
-  the resource here is not external but logical: the right to mutate shared
-  data.
+  the resource here is logical: temporary exclusive access to the data inside.
 
-- This right is represented by a `MutexGuard`. Only one can exist at a time.
-  While it lives, it provides `&mut T` access.
+- This right is represented by a `MutexGuard`. Only one guard for this mutex can
+  exist at a time. While it lives, it provides `&mut T` access.
 
 - Although `lock()` takes `&self`, it returns a `MutexGuard` with mutable
-  access. This is possible through interior mutability: a common pattern for
-  safe shared-state mutation.
+  access. This works through _interior mutability_, where a type manages its own
+  borrowing rules internally to allow mutation through `&self`.
 
 - `MutexGuard` implements `Deref` and `DerefMut`, making access ergonomic. You
   lock the mutex, use the guard like a `&mut T`, and the lock is released
   automatically when the guard goes out of scope.
 
-- The release is handled by `Drop`. There is no need to call a separate unlock
-  function — this is RAII in action.
+- The release is handled by `Drop`. You never call an explicit unlock function.
+  The guard’s `Drop` implementation releases the lock automatically.
 
 </details>

src/idiomatic/leveraging-the-type-system/raii/scope_guard.md

@@ -1,9 +1,9 @@
 # Scope Guards
 
-A scope guard uses the `Drop` trait to ensure cleanup code runs automatically
-when a scope exits — even if due to an error.
+A scope guard uses the `Drop` trait to run cleanup code automatically when a
+scope exits — even during unwinding.
 
-```rust,editable
+```rust,editable,compile_fail
 use scopeguard::{ScopeGuard, guard};
 use std::fs::{self, File};
 use std::io::Write;
@@ -36,17 +36,18 @@ fn main() {
 
 <details>
 
-- This example simulates an HTTP download. We create a temporary file first,
+- This example models a download workflow. We create a temporary file first,
   then use a scope guard to ensure that the file is deleted if the download
   fails.
 
 - The guard is placed directly after creating the file, so even if `writeln!()`
   fails, the file will still be cleaned up. This ordering is essential for
   correctness.
 
-- The guard's closure runs on scope exit unless defused with
-  `ScopeGuard::into_inner`. In the success path, we defuse it to preserve the
-  file.
+- The guard's closure runs on scope exit unless it is _defused_ with
+  `ScopeGuard::into_inner` (removing the value so the guard does nothing on
+  drop). In the success path, we call `into_inner` so the guard will not delete
+  the file.
 
 - This pattern is useful when you want fallbacks or cleanup code to run
   automatically but only if success is not explicitly signaled.