From 6a3d022d6d31b65769e87d0cca16cc1611aeeaec Mon Sep 17 00:00:00 2001 From: Lokathor Date: Mon, 10 Dec 2018 10:58:37 -0700 Subject: [PATCH] introduction improvements --- book/src/00-introduction/00-index.md | 13 +++++++++---- book/src/00-introduction/05-newtype.md | 22 ++++++++++++++++------ 2 files changed, 25 insertions(+), 10 deletions(-) diff --git a/book/src/00-introduction/00-index.md b/book/src/00-introduction/00-index.md index 6663e2b..0567c77 100644 --- a/book/src/00-introduction/00-index.md +++ b/book/src/00-introduction/00-index.md @@ -10,7 +10,12 @@ of the pages listed in the Table Of Contents. ## Feedback -It's also often hard to tell when you've explained something properly to someone -who doesn't understand the concept yet. Please, if things don't make sense then -[file an issue](https://github.com/rust-console/gba/issues) about it so I know -where things need to improve. +It's very often hard to tell when you've explained something properly. In the +same way that your brain will read over small misspellings and correct things +into the right word, if an explanation for something you already understand +accidentally skips over some small detail then your brain can fill in the gaps +without you realizing it. + +**Please**, if things don't make sense then [file an +issue](https://github.com/rust-console/gba/issues) about it so I know where +things need to improve. diff --git a/book/src/00-introduction/05-newtype.md b/book/src/00-introduction/05-newtype.md index 214250d..02c9676 100644 --- a/book/src/00-introduction/05-newtype.md +++ b/book/src/00-introduction/05-newtype.md @@ -111,12 +111,22 @@ macro_rules! newtype { ``` That seems like enough for all of our examples, so we'll stop there. We could -add more things, such as making the `From` impl optional (because what if you -shouldn't unwrap it for some weird reason?), allowing for more precise -visibility controls (on both the newtype overall and the inner field), and maybe -even other things I can't think of right now. We won't really need those in our -example code for this book, so it's probably nicer to just keep the macro -simpler and quit while we're ahead. +add more things: + +* Making the `From` impl being optional. We'd have to make the newtype + invocation be more complicated somehow, the user puts ", no-unwrap" after the + inner type declaration or something, or something like that. +* Allowing for more precise visibility controls on the wrapping type and on the + inner field. This would add a lot of line noise, so we'll just always have our + newtypes be `pub`. +* Allowing for generic newtypes, which might sound silly but that we'll actually + see an example of soon enough. To do this you might think that we can change + the `:ident` declarations to `:ty`, but then you can't use that captured type + when you declare the new wrapping type. The way you get around this is with a + proc-macro, which is a lot more powerful but which also requires that the + proc-macro be written in an entirely other crate. We don't need that much + power, so for our examples we'll go with the macro_rules version and just do + it by hand in the few cases where we need a generic newtype. **As a reminder:** remember that macros have to appear _before_ they're invoked in your source, so the `newtype` macro will always have to be at the very top of