Make some editorial improvements

We've merged PR rust-lang#1040, so we can remove the TODO and update the link
to point to the specific section.

We replace some commas with semicolons where that's the right thing to
do grammatically.

Where we have "an X is... they are...", we replace that with "an X
is... Xs are..." for reasons of avoiding a mismatch between the
plurality of the pronoun and its referent.

We replace "implementing type" and "defining type" with "type being
implemented" and "type being defined", since there is in general a
difference (e.g. "the driving force" vs "the force being driven"), and
these seem more like the latter than the former.

There's a place where we had said, "glob imports are allowed to import
conflicting names into the same *namespaces*" (emphasis added).  It
makes sense what this is trying to say by using the plural there.  But
it just reads better to use the singular, and if it's true for the
singular, it's clearly also true to the plural, so we make that
change.

src/items/modules.md

@@ -34,7 +34,7 @@ mod math {
 }
 ```
 
-Modules are defined in the [type namespace] of the module or block where it is located.
+Modules are defined in the [type namespace] of the module or block where they are located.
 It is an error to define multiple items with the same name in the same namespace within a module.
 See the [scopes chapter] for more details on restrictions and shadowing behavior.
 

src/items/static-items.md

@@ -11,7 +11,7 @@ memory location. Static items have the `static` lifetime, which outlives all
 other lifetimes in a Rust program. Static items do not call [`drop`] at the
 end of the program.
 
-The static declaration defines the static value in the [value namespace] of the module or block where it is located.
+The static declaration defines a static value in the [value namespace] of the module or block where it is located.
 
 The static initializer is a [constant expression] evaluated at compile time.
 Static initializers may refer to other statics.

src/items/structs.md

@@ -47,7 +47,7 @@ let p = Point {x: 10, y: 11};
 let px: i32 = p.x;
 ```
 
-A _tuple struct_ is a nominal [tuple type], also defined with the keyword `struct`.
+A _tuple struct_ is a nominal [tuple type], and is also defined with the keyword `struct`.
 In addition to defining a type, it also defines a constructor of the same name in the [value namespace].
 The constructor is a function which can be called to create a new instance of the struct.
 For example:

src/items/traits.md

@@ -17,8 +17,8 @@ interface consists of [associated items], which come in three varieties:
 - [types](associated-items.md#associated-types)
 - [constants](associated-items.md#associated-constants)
 
-The trait declaration defines the trait in the [type namespace] of the module or block where it is located.
-Associated items are defined as members of the trait within their respective namespaces: type namespace for associated types, and value namespace for constants and functions.
+The trait declaration defines a trait in the [type namespace] of the module or block where it is located.
+Associated items are defined as members of the trait within their respective namespaces. Associated types are defined in the type namespace. Associated constants and associated functions are defined in the value namespace.
 
 All traits define an implicit type parameter `Self` that refers to "the type
 that is implementing this interface". Traits may also contain additional type

src/items/type-aliases.md

@@ -8,7 +8,7 @@
 
 A _type alias_ defines a new name for an existing [type] in the [type namespace] of the module or block where it is located.
 Type aliases are declared with the keyword `type`.
-Every value has a single, specific type, but may implement several different traits, or be compatible with several different type constraints.
+Every value has a single, specific type, but may implement several different traits, and may be compatible with several different type constraints.
 
 For example, the following defines the type `Point` as a synonym for the type
 `(u8, u8)`, the type of pairs of unsigned 8 bit integers:

src/items/use-declarations.md

@@ -13,7 +13,7 @@ A _use declaration_ creates one or more local name bindings synonymous with
 some other [path]. Usually a `use` declaration is used to shorten the path
 required to refer to a module item. These declarations may appear in [modules]
 and [blocks], usually at the top.
-A `use` declaration is also sometimes called an _import_ or if it is public it is a _re-export_.
+A `use` declaration is also sometimes called an _import_, or, if it is public, a _re-export_.
 
 [path]: ../paths.md
 [modules]: modules.md
@@ -99,7 +99,7 @@ They may create bindings for:
 
 They cannot import [associated items], [generic parameters], [local variables], paths with [`Self`], or [tool attributes]. More restrictions are described below.
 
-`use` will create bindings for all [namespaces] from the imported entities, with the exception of a `self` import (described below) which only imports the type namespace.
+`use` will create bindings for all [namespaces] from the imported entities, with the exception that a `self` import will only import from the type namespace (as described below).
 For example, the following illustrates creating bindings for the same name in two namespaces:
 
 ```rust
@@ -111,12 +111,12 @@ mod stuff {
 use stuff::Foo;
 
 fn example() {
-    let ctor = Foo;  // From value namespace
-    let x: Foo = ctor(123);
+    let ctor = Foo; // Uses `Foo` from the value namespace.
+    let x: Foo = ctor(123); // Uses `Foo` From the type namespace.
 }
 ```
 
-> **Edition Differences**: In the 2015 edition, `use` paths are relative from the crate root.
+> **Edition differences**: In the 2015 edition, `use` paths are relative to the crate root.
 > For example:
 >
 > ```rust,edition2015
@@ -127,7 +127,8 @@ fn example() {
 > mod bar {
 >     // Resolves `foo` from the crate root.
 >     use foo::example::iter;
->     // :: prefix explicitly resolves `foo` from the crate root.
+>     // The `::` prefix explicitly resolves `foo`
+>     // from the crate root.
 >     use ::foo::baz::foobaz;
 > }
 >
@@ -154,25 +155,25 @@ mod inner {
 
 ## Brace syntax
 
-Braces can be used in the last segment of the path to import multiple entities from the previous segment or the current scope if there are no previous segments.
+Braces can be used in the last segment of the path to import multiple entities from the previous segment, or, if there are no previous segments, from the current scope.
 Braces can be nested, creating a tree of paths, where each grouping of segments is logically combined with its parent to create a full path.
 
 ```rust
 // Creates bindings to:
-// std::collections::BTreeSet
-// std::collections::hash_map
-// std::collections::hash_map::HashMap
+// - `std::collections::BTreeSet`
+// - `std::collections::hash_map`
+// - `std::collections::hash_map::HashMap`
 use std::collections::{BTreeSet, hash_map::{self, HashMap}};
 ```
 
 An empty brace does not import anything, though the leading path is validated that it is accessible.
-<!-- This is slightly wrong, see https://github.com/rust-lang/rust/issues/61826 -->
+<!-- This is slightly wrong, see: https://github.com/rust-lang/rust/issues/61826 -->
 
-> **Edition Differences**: In the 2015 edition, paths are relative to the crate root, so an import such as `use {foo, bar};` will import the names `foo` and `bar` from the crate root, whereas starting in 2018 those names are relative to the current scope.
+> **Edition differences**: In the 2015 edition, paths are relative to the crate root, so an import such as `use {foo, bar};` will import the names `foo` and `bar` from the crate root, whereas starting in 2018, those names are relative to the current scope.
 
 ## `self` imports
 
-The keyword `self` may be used in the [brace syntax](#brace-syntax) to create a binding of the parent entity under its own name.
+The keyword `self` may be used within [brace syntax](#brace-syntax) to create a binding of the parent entity under its own name.
 
 ```rust
 mod stuff {
@@ -204,7 +205,7 @@ mod bar {
 use bar::foo::{self};
 
 fn main() {
-    foo(); // Error, `foo` is a module
+    foo(); //~ ERROR `foo` is a module
 }
 ```
 
@@ -228,7 +229,8 @@ mod foo {
         V2,
     }
     pub fn bar() {
-        // Creates local aliases to V1 and V2 of the Example enum.
+        // Creates local aliases to `V1` and `V2`
+        // of the `Example` enum.
         use Example::*;
         let x = V1;
     }
@@ -240,9 +242,9 @@ That is, if there is a name already defined by another item in the same namespac
 For example:
 
 ```rust
-// This creates a binding to the `clashing::Foo` tuple struct constructor, but
-// does not import its type because that would conflict with the `Foo` struct
-// defined here.
+// This creates a binding to the `clashing::Foo` tuple struct
+// constructor, but does not import its type because that would
+// conflict with the `Foo` struct defined here.
 //
 // Note that the order of definition here is unimportant.
 use clashing::*;
@@ -251,11 +253,12 @@ struct Foo {
 }
 
 fn do_stuff() {
-    // Uses the constructor from clashing::Foo
+    // Uses the constructor from `clashing::Foo`.
     let f1 = Foo(123);
-    // The struct expression uses the type from the Foo struct defined above.
+    // The struct expression uses the type from
+    // the `Foo` struct defined above.
     let f2 = Foo { field: 1.0 };
-    // Also imported from the glob import.
+    // `Bar` is also in scope due to the glob import.
     let z = Bar {};
 }
 
@@ -268,7 +271,7 @@ mod clashing {
 `*` cannot be used as the first or intermediate segments.
 `*` cannot be used to import a module's contents into itself (such as `use self::*;`).
 
-> **Edition Differences**: In the 2015 edition, paths are relative to the crate root, so an import such as `use *;` is valid, and it means to import everything from the crate root.
+> **Edition differences**: In the 2015 edition, paths are relative to the crate root, so an import such as `use *;` is valid, and it means to import everything from the crate root.
 > This cannot be used in the crate root itself.
 
 ## Underscore Imports
@@ -317,10 +320,10 @@ m!(use std as _;);
 
 ## Restrictions
 
-The following are restrictions for valid `use` declarations.
+The following are restrictions for valid `use` declarations:
 
-* `use crate;` must use `as` to define the name to bind the crate root to.
-* `use {self};` is an error, there must be a leading segment when using `self`.
+* `use crate;` must use `as` to define the name to which to bind the crate root.
+* `use {self};` is an error; there must be a leading segment when using `self`.
 * As with any item definition, `use` imports cannot create duplicate bindings of the same name in the same namespace in a module or block.
 * `use` paths with `$crate` are not allowed in a [`macro_rules`] expansion.
 * `use` paths cannot refer to enum variants through a [type alias]. Example:
@@ -330,17 +333,17 @@ The following are restrictions for valid `use` declarations.
   }
   type TypeAlias = MyEnum;
 
-  use MyEnum::MyVariant; // OK
-  use TypeAlias::MyVariant; // ERROR
+  use MyEnum::MyVariant; //~ OK
+  use TypeAlias::MyVariant; //~ ERROR
   ```
 
 ## Ambiguities
 
 > **Note**: This section is incomplete.
 
-Some situations are an error when there is an ambiguity as to which name a `use` declaration refers to, when there are two name candidates that do not resolve to the same entity.
+Some situations are an error when there is an ambiguity as to which name a `use` declaration refers. This happens when there are two name candidates that do not resolve to the same entity.
 
-Glob imports are allowed to import conflicting names in the same namespaces as long as the name is not used or shadowed.
+Glob imports are allowed to import conflicting names in the same namespace as long as the name is not used or shadowed.
 Example:
 
 ```rust
@@ -353,11 +356,11 @@ mod bar {
 }
 
 use foo::*;
-use bar::*; // Ok, no name conflict.
+use bar::*; //~ OK, no name conflict.
 
 fn main() {
     // This would be an error, due to the ambiguity.
-    // let x = Qux;
+    //let x = Qux;
 }
 ```
 

src/paths.md

@@ -1,7 +1,7 @@
 # Paths
 
 A *path* is a sequence of one or more path segments separated by `::` tokens.
-They are used to refer to [items], values, [types], [macros], and [attributes].
+Paths are used to refer to [items], values, [types], [macros], and [attributes].
 
 Two examples of simple paths consisting of only identifier segments:
 
@@ -224,13 +224,12 @@ impl S {
 `Self`, with a capital "S", is used to refer to the current type being implemented or defined. It may be used in the following situations:
 
 * In a [trait] definition, it refers to the type implementing the trait.
-* In an [implementation], it refers to the implementing type.
+* In an [implementation], it refers to the type being implemented.
   When implementing a tuple or unit [struct], it also refers to the constructor in the [value namespace].
-* In the definition of a [struct], [enumeration], or [union], it refers to the defining type.
+* In the definition of a [struct], [enumeration], or [union], it refers to the type being defined.
   The definition is not allowed to be infinitely recursive (there must be an indirection).
 
-The scope of `Self` behaves similarly to a generic parameter, see the [scopes chapter] for more details.
-<!-- TODO: update link to #self-scope once https://github.com/rust-lang/reference/pull/1040 is merged. -->
+The scope of `Self` behaves similarly to a generic parameter; see the [`Self` scope] section for more details.
 
 `Self` can only be used as the first segment, without a preceding `::`.
 The `Self` path cannot include generic arguments (as in `Self::<i32>`).
@@ -257,16 +256,18 @@ impl T for S {
 }
 
 // `Self` is in scope within the generics of a trait definition,
-// to refer to the defining type.
+// to refer to the type being defined.
 trait Add<Rhs = Self> {
     type Output;
-    // `Self` can also reference associated items of the implementing types.
+    // `Self` can also reference associated items of the
+    // type being implemented.
     fn add(self, rhs: Rhs) -> Self::Output;
 }
 
 struct NonEmptyList<T> {
     head: T,
-    // A struct can reference itself (as long as it is not infinitely recursive).
+    // A struct can reference itself (as long as it is not
+    // infinitely recursive).
     tail: Option<Box<Self>>,
 }
 ```
@@ -420,11 +421,12 @@ mod without { // crate::without
 [_Type_]: types.md#type-expressions
 [_TypeNoBounds_]: types.md#type-expressions
 [_TypeParamBounds_]: trait-bounds.md
-[literal]: expressions/literal-expr.md
-[items]: items.md
 [implementations]: items/implementations.md
+[items]: items.md
+[literal]: expressions/literal-expr.md
 [use declarations]: items/use-declarations.md
 [IDENTIFIER]: identifiers.md
+[`Self` scope]: names/scopes.md#self-scope
 [`use`]: items/use-declarations.md
 [attributes]: attributes.md
 [enumeration]: items/enumerations.md
@@ -435,7 +437,6 @@ mod without { // crate::without
 [macros]: macros.md
 [mbe]: macros-by-example.md
 [patterns]: patterns.md
-[scopes chapter]: names/scopes.md
 [struct]: items/structs.md
 [trait implementations]: items/implementations.md#trait-implementations
 [trait]: items/traits.md