Merge pull request #62 from ferrous-systems/methods-and-traits

training-slides/src/SUMMARY.md

@@ -22,25 +22,30 @@
 
 # Applied Rust
 
--   [Method Syntax](./method-syntax.md)
--   [Macros](./macros.md)
--   [Defining and Implementing Traits](./traits.md)
+-   [Methods and Traits](./methods-traits.md)
 -   [Cargo Dependencies and Workspaces](./using-cargo.md)
 -   [Rust I/O Traits](./io.md)
--   [Generic over Types](./generics.md)
--   [Generic over Lifetimes](./lifetimes.md)
--   [Closures and the Fn Traits](./closures.md)
--   [Heap Allocation (Box, Rc and Cow)](./heap.md)
+-   [Generics](./generics.md)
+-   [Lifetimes](./lifetimes.md)
+-   [Heap Allocation (Box and Rc)](./heap.md)
 -   [Shared Mutability (Cell, RefCell)](./shared-mutability.md)
 -   [Thread Safety (Send/Sync, Arc, Mutex)](./thread-safety.md)
+-   [Closures and the Fn/FnOnce/FnMut traits](./closures.md)
 -   [Spawning Threads and Scoped Threads](./spawning-threads.md)
 
 # Additional Material
 
 -   [Advanced Generics](./advanced-generics-bounds.md)
+-   [Debugging Rust](./debugging-rust.md)
+-   [Deref Coercions](./deref-coercions.md)
+-   [Design Patterns](./design-patterns.md)
+-   [Documentation](./documentation.md)
+-   [Drop, Panic and Abort](./drop-panic-abort.md)
 -   [Dynamic Dispatch](./dynamic-dispatch.md)
 -   [Foreign Function Interface](./ffi.md)
 -   [libcore and libstd](./libcore-and-libstd.md)
+-   [Macros](./macros.md)
+-   [Property Testing](./property-testing.md)
 -   [Send and Sync](./send-and-sync.md)
 -   [Serde](./serde.md)
 -   [Standard Types](./standard-types.md)
@@ -50,9 +55,3 @@
 -   [Unsafe Rust](./unsafe.md)
 -   [WASM](./wasm.md)
 -   [Working with Nightly](./working-with-nighly.md)
--   [Property Testing](./property-testing.md)
--   [Drop, Panic and Abort](./drop-panic-abort.md)
--   [Documentation](./documentation.md)
--   [Design Patterns](./design-patterns.md)
--   [Deref Coercions](./deref-coercions.md)
--   [Debugging Rust](./debugging-rust.md)

training-slides/src/macros.md

@@ -13,6 +13,8 @@ Macros can be used to things such as:
 * Declarative
 * Procedural
 
+# Declarative Macros
+
 ## Declarative Macros
 
 * Defined using `macro_rules!`
@@ -63,7 +65,7 @@ macro_rules! vec {
 
 Note:
 
-The actual macro is more complicated as it sets the `Vec` to have the correct capacity up front, to avoid re-allocation during the pushing of the values.
+The actual macro is more complicated as it sets the `Vec` to have the correct capacity up front, to avoid re-allocation during the pushing of the values. Any new variables we introduce are given a *colour* to distinguish them from any the caller had created in the same scope.
 
 ## `println!` and friends
 
@@ -103,6 +105,8 @@ This is a simplified example - the real output is slightly more complicated, and
 
 * When there are no other good alternatives
 
+# Procedural macros
+
 ## Procedural macros
 
 * A procedural macro is a function that takes some code as input, and produces some code.
@@ -117,10 +121,12 @@ This is a simplified example - the real output is slightly more complicated, and
 
 ## Custom `#[derive]` macros
 
-Work like the built-in Rust derives:
+Work like the built-in Rust derives, once you've imported them:
 
 ```rust [] ignore
-#[derive(Debug, Clone, serde::Serialize)]
+use serde::Serialize;
+
+#[derive(Debug, Clone, Serialize)]
 struct Square {
     width: u32,
 }
@@ -159,3 +165,14 @@ Called like a function:
 ```rust ignore
 let query = sqlx::query!("SELECT * FROM `person`");
 ```
+
+## Downsides of Procedural Macros
+
+* Can be difficult to debug
+* Slows down compilation a lot
+* Have to be stored in a separate crate
+  * You're basically building compiler plug-ins at build time
+
+## When Should You Use Procedural Macros?
+
+* When it saves your users a sufficient amount of work