Clarifications, grammar, punctuation

Author: carols10cents

_posts/2018-10-25-Rust-1.30.md

@@ -40,18 +40,19 @@ struct Pet {
 }
 ```
 
-And convert a `Pet` to and from JSON.
+And convert a `Pet` to and from JSON because `serde_json` defined `Serialize` and
+`Deserialize` in a procedural macro.
 
 Rust expands on this by adding the ability to define two other kinds of
 advanced macros, "attribute-like procedrual macros" and "function-like
 procedural macros."
 
-Attribute-like macros are similar to custom derive macros, but instead of
-generating code for `#[derive]`, they allow you to create new, custom
-attributes of your own. They're also more flexible; derive only works for
-structs and enums; attributes can go on other places as well, like functions.
-As an example of using an attribute-like macro, you might have something like
-this when using a web application framework:
+Attribute-like macros are similar to custom derive macros, but instead of generating code
+for only the `#[derive]` attribute, they allow you to create new, custom attributes of
+your own. They're also more flexible: derive only works for structs and enums, but
+attributes can go on other places, like functions. As an example of using an
+attribute-like macro, you might have something like this when using a web application
+framework:
 
 ```
 #[route(GET, "/")]
@@ -66,7 +67,7 @@ procedural macro. Its signature would look like this:
 pub fn route(attr: TokenStream, item: TokenStream) -> TokenStream {
 ```
 
-Here, we have two input `TokenStreams`; the first is for the contents of the
+Here, we have two input `TokenStreams`: the first is for the contents of the
 attribute itself, that is, the `GET, "/"` stuff. The second is the body of the
 thing the attribute is attached to, in this case, `fn index() {}` and the rest
 of the function's body.
@@ -86,12 +87,12 @@ syntactically correct. This macro would be defined like this:
 pub fn sql(input: TokenStream) -> TokenStream {
 ```
 
-This is similar to the derive macro's signature: we get in the tokens that
-are inside of the parentheses, and return the code we wanted to generate.
+This is similar to the derive macro's signature: we get the tokens that
+are inside of the parentheses and return the code we want to generate.
 
 ### `use` and macros
 
-You can now [use `use` to bring macros into scope][externmacro]. For example, 
+You can now [bring macros into scope with the `use` keyword][externmacro]. For example,
 to use `serde-json`'s `json` macro, you used to write:
 
 ```rust
@@ -125,7 +126,7 @@ let john = json!({
 });
 ```
 
-This brings macros more in line with other items, and removes the need for
+This brings macros more in line with other items and removes the need for
 `macro_use` annotations.
 
 [externmacro]: https://github.com/rust-lang/rust/pull/50911/
@@ -138,7 +139,7 @@ its rules felt awkward in practice. These changes are the first steps we're
 taking to make the module system feel more straightforward.
 
 [`mod.rs` files are now optional][optionalmod]. Imagine we had a `foo`
-submodule, with a `bar` submodule of its own. The directory layout would
+submodule with a `bar` submodule of its own. The directory layout would
 look like this:
 
 ```text
@@ -173,15 +174,14 @@ existed, the project would look like this:
 ```
 
 Many users found the need to move `foo.rs` into `foo/mod.rs` to be an
-unncessary, strage requirement. With the new layout, you create `src/foo` and
-put `bar.rs` in it and you're done.
+unncessary, strage requirement. With the new layout, you create `src/foo`,
+put `bar.rs` in it, and you're done.
 
 [optionalmod]: https://github.com/rust-lang/rust/pull/54072
 
-There's two changes to `use` as well. Well, three changes: we already
-mentioned that you can use `use` to bring macros into scope in the macros
-section. There's two more. The first is that you can [`use` an extern crate
-without needing `::`][nocoloncolon], that is:
+There's two changes to `use` as well, in addition to the aforementioned change for
+macros. The first is that you can now always [`use` an extern crate without
+`::`][nocoloncolon], that is:
 
 ```rust
 // old
@@ -215,21 +215,21 @@ mod foo {
     use serde_json;
 
     fn baz() {
-        // the other option is to use `::serde_json`, so we're using an absolute path rather than
-        // a relative one
+        // the other option is to use `::serde_json`, so we're using an absolute path
+        // rather than a relative one
         let json = ::serde_json::from_str("...");
     }
 }
 ```
 
-Moving a function to a submodule and having your imports break was not a
-great experience. Now, `use` will check to see if the first part of the path
-and see if it's one of your `extern crate`s, and if it is, use it, regardless
-of where you're at in the module hierarchy.
+Moving a function to a submodule and having your imports break was not a great
+experience. Now, `use` will check the first part of the path and see if it's an `extern
+crate`, and if it is, use it regardless of where you're at in the module hierarchy.
 
 [nocoloncolon]: https://github.com/rust-lang/rust/pull/54404/
 
-Finally, you can also [use `crate` with `use`][usecrate]:
+Finally, [`use` also supports bringing items into scope with paths starting with
+`crate`][usecrate]:
 
 ```rust
 mod foo {
@@ -240,14 +240,17 @@ mod foo {
 
 // old
 use ::foo::bar;
+// or
+use foo::bar;
 
 // new
 use crate::foo::bar;
 ```
 
-The `crate` keyword at the start of the path indicates that you would like
-the path to start at your crate root. `use` previously would always start at
-the crate root, but other paths would start at the local path, meaning:
+The `crate` keyword at the start of the path indicates that you would like the path to
+start at your crate root. Previously, paths specified after `use` would always start at
+the crate root, but paths referring to items directly would start at the local path,
+meaning the behavior of paths was inconsistent:
 
 ```rust
 mod foo {
@@ -260,25 +263,29 @@ mod baz {
     pub fn qux() {
         // old
         ::foo::bar();
+        // does not work, which is different than with `use`:
+        // foo::bar();
 
         // new
         crate::foo::bar();
     }
 }
 ```
 
-This will hopefully make absolute paths a bit more clear, and remove some of
-the ugliness of leading `::`.
+Once this style becomes widely used, this will hopefully make absolute paths a bit more
+clear and remove some of the ugliness of leading `::`.
 
-All of these changes combined lead to a more straightforward understanding of
-how paths resolve. When you see a path like `a::b::c`, you can ask:
+All of these changes combined lead to a more straightforward understanding of how paths
+resolve. Wherever you see a path like `a::b::c` someplace other than a `use` statement,
+you can ask:
 
 * Is `a` the name of a crate? Then we're looking for `b::c` inside of it.
 * Is `a` the keyword `crate`? Then we're looking for `b::c` from the root of our crate.
 * Otherwise, we're looking for `a::b::c` from the current spot in the module hierarchy.
 
-Since these rules apply uniformly everywhere, you'll need to tweak your
-imports much less when moving code around.
+The old behavior of `use` paths always starting from the crate root still applies. But
+after making a one-time switch to the new style, these rules will apply uniformly to
+paths everywhere, and you'll need to tweak your imports much less when moving code around.
 
 [usecrate]: https://github.com/rust-lang/rust/pull/54404/
 
@@ -299,9 +306,10 @@ fn r#for() {
 r#for();
 ```
 
-This doesn't have many use cases today, but will once you are trying to use a
-Rust 2015 crate with a Rust 2018 project, and vice-versa; we'll explain more
-in that upcoming blog post.
+This doesn't have many use cases today, but will once you are trying to use a Rust 2015
+crate with a Rust 2018 project and vice-versa because the set of keywords will be
+different in the two editions; we'll explain more in the upcoming blog post about
+Rust 2018.
 
 [rawidents]: https://github.com/rust-lang/rust/pull/53236/
 
@@ -327,16 +335,15 @@ release](https://github.com/rust-lang/rust/blob/master/RELEASES.md#stabilized-ap
 
 Additionally, the standard library has long had functions like `trim_left` to eliminate
 whitespace on one side of some text. However, when considering RTL languages, the meaning
-of "right" and "left" get confusing. As such, we're introducing some new names for these
+of "right" and "left" gets confusing. As such, we're introducing new names for these
 APIs:
 
 * `trim_left` -> `trim_start`
 * `trim_right` -> `trim_end`
 * `trim_left_matches` -> `trim_start_matches`
 * `trim_right_matches` -> `trim_end_matches`
 
-We plan to deprecate (but not removing, of course) the old names in Rust
-1.33.
+We plan to deprecate (but not remove, of course) the old names in Rust 1.33.
 
 See the [detailed release notes][notes] for more.