From 2aadaad918b1d0a887c6c513a0e9ca49aab1d74e Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Sun, 27 Jun 2021 12:31:20 -0700
Subject: [PATCH 01/12] Specify how names are introduced.

This is just a first pass to specifying how each thing introduces
a name, and where it is introduced. This is missing `use` and `Self`.
(And a few things I don't feel like need elaboration, like loop labels,
but those can be added if desired.)
---
 src/items/constant-items.md  |  3 +++
 src/items/enumerations.md    | 49 ++++++++++++++++++++++++++++--------
 src/items/extern-crates.md   |  9 +++----
 src/items/external-blocks.md |  3 +++
 src/items/functions.md       |  3 ++-
 src/items/modules.md         | 10 ++++----
 src/items/static-items.md    |  3 +++
 src/items/structs.md         | 28 ++++++++++++---------
 src/items/traits.md          |  4 +++
 src/items/type-aliases.md    |  8 +++---
 src/items/unions.md          |  2 ++
 src/patterns.md              |  3 ++-
 src/procedural-macros.md     |  7 +++++-
 13 files changed, 93 insertions(+), 39 deletions(-)

diff --git a/src/items/constant-items.md b/src/items/constant-items.md
index 9d48762ef..9fb218519 100644
--- a/src/items/constant-items.md
+++ b/src/items/constant-items.md
@@ -11,6 +11,8 @@ context when used. This includes usage of constants from external crates, and
 non-[`Copy`] types. References to the same constant are not necessarily
 guaranteed to refer to the same memory address.
 
+The constant declaration defines the constant value in the [value namespace] of the module or block where it is located.
+
 Constants must be explicitly typed. The type must have a `'static` lifetime: any
 references in the initializer must have `'static` lifetimes.
 
@@ -115,3 +117,4 @@ fn unused_generic_function<T>() {
 [_Type_]: ../types.md#type-expressions
 [_Expression_]: ../expressions.md
 [`Copy`]: ../special-types-and-traits.md#copy
+[value namespace]: ../names/namespaces.md
diff --git a/src/items/enumerations.md b/src/items/enumerations.md
index 0d42bfd05..043cbe962 100644
--- a/src/items/enumerations.md
+++ b/src/items/enumerations.md
@@ -30,6 +30,7 @@ nominal [enumerated type] as well as a set of *constructors*, that can be used
 to create or pattern-match values of the corresponding enumerated type.
 
 Enumerations are declared with the keyword `enum`.
+The `enum` declaration defines the enumeration type in the [type namespace] of the module or block where it is located.
 
 An example of an `enum` item and its use:
 
@@ -80,6 +81,27 @@ enum Enum {
 }
 ```
 
+Variant constructors are similar to [struct] definitions, and can be referenced by a path from the enumeration name, including in [use declarations].
+The constructors are defined in both the [type namespace] and [value namespace] within the enumeration.
+
+A struct-like variant can be instantiated with a [struct expression].
+A tuple-like variant can be instantiated with a [call expression].
+A unit-like variant can be instantiated with a [path expression].
+For example:
+
+```rust
+enum Examples {
+    UnitLike,
+    TupleLike(i32),
+    StructLike { value: i32 },
+}
+
+use Examples::*; // Creates aliases to all variants.
+let x = UnitLike; // Path expression of the const item.
+let y = TupleLike(123); // Call expression.
+let z = StructLike { value: 123 }; // Struct expression.
+```
+
 <span id="custom-discriminant-values-for-fieldless-enumerations"></span>
 ## Discriminants
 
@@ -299,20 +321,27 @@ enum E {
 }
 ```
 
-[IDENTIFIER]: ../identifiers.md
-[_GenericParams_]: generics.md
-[_WhereClause_]: generics.md#where-clauses
 [_Expression_]: ../expressions.md
-[_TupleFields_]: structs.md
+[_GenericParams_]: generics.md
 [_StructFields_]: structs.md
+[_TupleFields_]: structs.md
 [_Visibility_]: ../visibility-and-privacy.md
-[enumerated type]: ../types/enum.md
+[_WhereClause_]: generics.md#where-clauses
+[`C` representation]: ../type-layout.md#the-c-representation
 [`mem::discriminant`]: ../../std/mem/fn.discriminant.html
-[never type]: ../types/never.md
-[unit-only]: #unit-only-enum
-[numeric cast]: ../expressions/operator-expr.md#semantics
+[call expression]: ../expressions/call-expr.md
 [constant expression]: ../const_eval.md#constant-expressions
 [default representation]: ../type-layout.md#the-default-representation
-[primitive representation]: ../type-layout.md#primitive-representations
-[`C` representation]: ../type-layout.md#the-c-representation
+[enumerated type]: ../types/enum.md
 [Field-less enums]: #field-less-enum
+[IDENTIFIER]: ../identifiers.md
+[never type]: ../types/never.md
+[numeric cast]: ../expressions/operator-expr.md#semantics
+[path expression]: ../expressions/path-expr.md
+[primitive representation]: ../type-layout.md#primitive-representations
+[struct expression]: ../expressions/struct-expr.md
+[struct]: structs.md
+[type namespace]: ../names/namespaces.md
+[unit-only]: #unit-only-enum
+[use declarations]: use-declarations.md
+[value namespace]: ../names/namespaces.md
diff --git a/src/items/extern-crates.md b/src/items/extern-crates.md
index 9dd6a5eb9..523e9720d 100644
--- a/src/items/extern-crates.md
+++ b/src/items/extern-crates.md
@@ -11,11 +11,9 @@
 > &nbsp;&nbsp; `as` ( [IDENTIFIER] | `_` )
 
 An _`extern crate` declaration_ specifies a dependency on an external crate.
-The external crate is then bound into the declaring scope as the [identifier]
-provided in the `extern crate` declaration. Additionally, if the `extern
-crate` appears in the crate root, then the crate name is also added to the
-[extern prelude], making it automatically in scope in all modules. The `as`
-clause can be used to bind the imported crate to a different name.
+The external crate is then bound into the declaring scope as the given [identifier] in the [type namespace].
+Additionally, if the `extern crate` appears in the crate root, then the crate name is also added to the [extern prelude], making it automatically in scope in all modules.
+The `as` clause can be used to bind the imported crate to a different name.
 
 The external crate is resolved to a specific `soname` at compile time, and a
 runtime linkage requirement to that `soname` is passed to the linker for
@@ -74,6 +72,7 @@ crate to access only its macros.
 [extern prelude]: ../names/preludes.md#extern-prelude
 [`macro_use` prelude]: ../names/preludes.md#macro_use-prelude
 [`crate_name` attributes]: ../crates-and-source-files.md#the-crate_name-attribute
+[type namespace]: ../names/namespaces.md
 
 <script>
 (function() {
diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md
index efbd08256..9abce3fd4 100644
--- a/src/items/external-blocks.md
+++ b/src/items/external-blocks.md
@@ -21,6 +21,8 @@ Two kinds of item _declarations_ are allowed in external blocks: [functions] and
 [statics]. Calling functions or accessing statics that are declared in external
 blocks is only allowed in an `unsafe` context.
 
+The external block defines its functions and statics in the [value namespace] of the module or block where it is located.
+
 The `unsafe` keyword is syntactically allowed to appear before the `extern`
 keyword, but it is rejected at a semantic level. This allows macros to consume
 the syntax and make use of the `unsafe` keyword, before removing it from the
@@ -342,3 +344,4 @@ restrictions as [regular function parameters].
 [`verbatim` documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-verbatim
 [`dylib` versus `raw-dylib`]: #dylib-versus-raw-dylib
 [PE Format]: https://learn.microsoft.com/windows/win32/debug/pe-format#import-name-type
+[value namespace]: ../names/namespaces.md
diff --git a/src/items/functions.md b/src/items/functions.md
index 47059ad3a..ae698fba2 100644
--- a/src/items/functions.md
+++ b/src/items/functions.md
@@ -45,7 +45,7 @@
 A _function_ consists of a [block] (that's the _body_ of the function),
 along with a name, a set of parameters, and an output type.
 Other than a name, all these are optional.
-Functions are declared with the keyword `fn`.
+Functions are declared with the keyword `fn` which defines the given name in the [value namespace] of the module or block where it is located.
 Functions may declare a set of *input* [*variables*][variables] as parameters, through which the caller passes arguments into the function, and the *output* [*type*][type] of the value the function will return to its caller on completion.
 If the output type is not explicitly stated, it is the [unit type].
 
@@ -413,4 +413,5 @@ fn foo_oof(#[some_inert_attribute] arg: u8) {
 [method]: associated-items.md#methods
 [associated function]: associated-items.md#associated-functions-and-methods
 [implementation]: implementations.md
+[value namespace]: ../names/namespaces.md
 [variadic function]: external-blocks.md#variadic-functions
diff --git a/src/items/modules.md b/src/items/modules.md
index 2a0ad55c5..375cf2b56 100644
--- a/src/items/modules.md
+++ b/src/items/modules.md
@@ -34,11 +34,9 @@ mod math {
 }
 ```
 
-Modules and types share the same namespace. Declaring a named type with the
-same name as a module in scope is forbidden: that is, a type definition, trait,
-struct, enumeration, union, type parameter or crate can't shadow the name of a
-module in scope, or vice versa. Items brought into scope with `use` also have
-this restriction.
+Modules are defined in the [type namespace] of the module or block where it is 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.
 
 The `unsafe` keyword is syntactically allowed to appear before the `mod`
 keyword, but it is rejected at a semantic level. This allows macros to consume
@@ -149,7 +147,9 @@ The built-in attributes that have meaning on a module are [`cfg`],
 [attribute]: ../attributes.md
 [items]: ../items.md
 [module path]: ../paths.md
+[scopes chapter]: ../names/scopes.md
 [the lint check attributes]: ../attributes/diagnostics.md#lint-check-attributes
+[type namespace]: ../names/namespaces.md
 
 <script>
 (function() {
diff --git a/src/items/static-items.md b/src/items/static-items.md
index d1e461899..ee93b931e 100644
--- a/src/items/static-items.md
+++ b/src/items/static-items.md
@@ -11,6 +11,8 @@ 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 initializer is a [constant expression] evaluated at compile time.
 Static initializers may refer to other statics.
 
@@ -136,3 +138,4 @@ following are true:
 [IDENTIFIER]: ../identifiers.md
 [_Type_]: ../types.md#type-expressions
 [_Expression_]: ../expressions.md
+[value namespace]: ../names/namespaces.md
diff --git a/src/items/structs.md b/src/items/structs.md
index 9523e7bfb..36d49e634 100644
--- a/src/items/structs.md
+++ b/src/items/structs.md
@@ -37,6 +37,7 @@
 > &nbsp;&nbsp; [_Type_]
 
 A _struct_ is a nominal [struct type] defined with the keyword `struct`.
+A struct declaration defines the given name in the [type namespace] of the module or block where it is located.
 
 An example of a `struct` item and its use:
 
@@ -46,11 +47,10 @@ 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`. For example:
-
-[struct type]: ../types/struct.md
-[tuple type]: ../types/tuple.md
+A _tuple struct_ is a nominal [tuple type], 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:
 
 ```rust
 struct Point(i32, i32);
@@ -59,7 +59,7 @@ let px: i32 = match p { Point(x, _) => x };
 ```
 
 A _unit-like struct_ is a struct without any fields, defined by leaving off the
-list of fields entirely. Such a struct implicitly defines a constant of its
+list of fields entirely. Such a struct implicitly defines a [constant] of its
 type with the same name. For example:
 
 ```rust
@@ -78,11 +78,15 @@ let c = [Cookie, Cookie {}, Cookie, Cookie {}];
 The precise memory layout of a struct is not specified. One can specify a
 particular layout using the [`repr` attribute].
 
-[`repr` attribute]: ../type-layout.md#representations
-
-[_OuterAttribute_]: ../attributes.md
-[IDENTIFIER]: ../identifiers.md
 [_GenericParams_]: generics.md
-[_WhereClause_]: generics.md#where-clauses
-[_Visibility_]: ../visibility-and-privacy.md
+[_OuterAttribute_]: ../attributes.md
 [_Type_]: ../types.md#type-expressions
+[_Visibility_]: ../visibility-and-privacy.md
+[_WhereClause_]: generics.md#where-clauses
+[`repr` attribute]: ../type-layout.md#representations
+[IDENTIFIER]: ../identifiers.md
+[constant]: constant-items.md
+[struct type]: ../types/struct.md
+[tuple type]: ../types/tuple.md
+[type namespace]: ../names/namespaces.md
+[value namespace]: ../names/namespaces.md
diff --git a/src/items/traits.md b/src/items/traits.md
index a74d7cb84..677199fc8 100644
--- a/src/items/traits.md
+++ b/src/items/traits.md
@@ -17,6 +17,9 @@ 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.
+
 All traits define an implicit type parameter `Self` that refers to "the type
 that is implementing this interface". Traits may also contain additional type
 parameters. These type parameters, including `Self`, may be constrained by
@@ -345,3 +348,4 @@ fn main() {
 [`Rc<Self>`]: ../special-types-and-traits.md#rct
 [`async`]: functions.md#async-functions
 [`const`]: functions.md#const-functions
+[type namespace]: ../names/namespaces.md
diff --git a/src/items/type-aliases.md b/src/items/type-aliases.md
index 24c6f4eee..5699298d5 100644
--- a/src/items/type-aliases.md
+++ b/src/items/type-aliases.md
@@ -6,10 +6,9 @@
 >              ( `:` [_TypeParamBounds_] )<sup>?</sup>
 >              [_WhereClause_]<sup>?</sup> ( `=` [_Type_] [_WhereClause_]<sup>?</sup>)<sup>?</sup> `;`
 
-A _type alias_ defines a new name for an existing [type]. 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.
+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.
 
 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:
@@ -53,3 +52,4 @@ the equals sign (like `type TypeAlias<T> = Bar<T> where T: Foo`) are preferred.
 [trait]: traits.md
 [type]: ../types.md
 [trait impl]: implementations.md#trait-implementations
+[type namespace]: ../names/namespaces.md
diff --git a/src/items/unions.md b/src/items/unions.md
index 049564f2b..ed3ba5ae9 100644
--- a/src/items/unions.md
+++ b/src/items/unions.md
@@ -7,6 +7,7 @@
 
 A union declaration uses the same syntax as a struct declaration, except with
 `union` in place of `struct`.
+A union declaration defines the given name in the [type namespace] of the module or block where it is located.
 
 ```rust
 #[repr(C)]
@@ -179,4 +180,5 @@ checking, etc etc etc).
 [boolean type]: ../types/boolean.md
 [ManuallyDrop]: ../../std/mem/struct.ManuallyDrop.html
 [the C representation]: ../type-layout.md#reprc-unions
+[type namespace]: ../names/namespaces.md
 [undefined behavior]: ../behavior-considered-undefined.html
diff --git a/src/patterns.md b/src/patterns.md
index a8b09a9ee..0f186bf79 100644
--- a/src/patterns.md
+++ b/src/patterns.md
@@ -171,7 +171,7 @@ for i in -2..5 {
 > _IdentifierPattern_ :\
 > &nbsp;&nbsp; &nbsp;&nbsp; `ref`<sup>?</sup> `mut`<sup>?</sup> [IDENTIFIER] (`@` [_PatternNoTopAlt_] ) <sup>?</sup>
 
-Identifier patterns bind the value they match to a variable.
+Identifier patterns bind the value they match to a variable in the [value namespace].
 The identifier must be unique within the pattern.
 The variable will shadow any variables of the same name in scope.
 The [scope] of the new binding depends on the context of where the pattern is used (such as a `let` binding or a `match` arm).
@@ -888,3 +888,4 @@ For example, `x @ A(..) | B(..)` will result in an error that `x` is not bound i
 [tuples]: types/tuple.md
 [scrutinee]: glossary.md#scrutinee
 [type coercions]: type-coercions.md
+[value namespace]: names/namespaces.md
diff --git a/src/procedural-macros.md b/src/procedural-macros.md
index 32b847c0f..c5af448b7 100644
--- a/src/procedural-macros.md
+++ b/src/procedural-macros.md
@@ -11,8 +11,9 @@ Procedural macros allow you to run code at compile time that operates over Rust
 syntax, both consuming and producing Rust syntax. You can sort of think of
 procedural macros as functions from an AST to another AST.
 
-Procedural macros must be defined in a crate with the [crate type] of
+Procedural macros must be defined in the root of a crate with the [crate type] of
 `proc-macro`.
+The macros may not be used from the crate where they are defined, and can only be used when imported in another crate.
 
 > **Note**: When using Cargo, Procedural macro crates are defined with the
 > `proc-macro` key in your manifest:
@@ -77,6 +78,7 @@ These macros are defined by a [public]&#32;[function] with the `proc_macro`
 [attribute] and a signature of `(TokenStream) -> TokenStream`. The input
 [`TokenStream`] is what is inside the delimiters of the macro invocation and the
 output [`TokenStream`] replaces the entire macro invocation.
+The `proc_macro` attribute defines the macro in the [macro namespace] in the root of the crate.
 
 For example, the following macro definition ignores its input and outputs a
 function `answer` into its scope.
@@ -120,6 +122,7 @@ They can also define [derive macro helper attributes].
 
 Custom derive macros are defined by a [public]&#32;[function] with the
 `proc_macro_derive` attribute and a signature of `(TokenStream) -> TokenStream`.
+The `proc_macro_derive` attribute defines the custom derive in the [macro namespace] in the root of the crate.
 
 The input [`TokenStream`] is the token stream of the item that has the `derive`
 attribute on it. The output [`TokenStream`] must be a set of items that are
@@ -206,6 +209,7 @@ the attribute is written as a bare attribute name, the attribute
 [`TokenStream`] is empty. The second [`TokenStream`] is the rest of the [item]
 including other [attributes] on the [item]. The returned [`TokenStream`]
 replaces the [item] with an arbitrary number of [items].
+The `proc_macro_attribute` attribute defines the attribute in the [macro namespace] in the root of the crate.
 
 For example, this attribute macro takes the input stream and returns it as is,
 effectively being the no-op of attributes.
@@ -356,6 +360,7 @@ their equivalent `#[doc = r"str"]` attributes when passed to macros.
 [inert]: attributes.md#active-and-inert-attributes
 [item]: items.md
 [items]: items.md
+[macro namespace]: names/namespaces.md
 [module]: items/modules.md
 [patterns]: patterns.md
 [public]: visibility-and-privacy.md

From 5de59db02434e8fb6343efea696d36de0c5e7d4d Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Sun, 27 Jun 2021 14:16:33 -0700
Subject: [PATCH 02/12] Clean up a few uses of the word "namespace".

Since "namespace" has a specific meaning in Rust, I feel like it would
be good not to overload it too much with the sense of a scope container
like a C++ namespace.
---
 src/attributes.md       |  2 +-
 src/items/generics.md   | 11 ++++-------
 src/names/namespaces.md |  3 ---
 src/paths.md            | 16 +++++++---------
 4 files changed, 12 insertions(+), 20 deletions(-)

diff --git a/src/attributes.md b/src/attributes.md
index 08b6c0692..a56e276f6 100644
--- a/src/attributes.md
+++ b/src/attributes.md
@@ -174,7 +174,7 @@ active. All other attributes are inert.
 ## Tool attributes
 
 The compiler may allow attributes for external tools where each tool resides
-in its own namespace in the [tool prelude]. The first segment of the attribute
+in its own module in the [tool prelude]. The first segment of the attribute
 path is the name of the tool, with one or more additional segments whose
 interpretation is up to the tool.
 
diff --git a/src/items/generics.md b/src/items/generics.md
index 65f17bd5b..9b756594b 100644
--- a/src/items/generics.md
+++ b/src/items/generics.md
@@ -48,12 +48,8 @@ referred to with path syntax.
 
 ### Const generics
 
-*Const generic parameters* allow items to be generic over constant values. The
-const identifier introduces a name for the constant parameter, and all
-instances of the item must be instantiated with a value of the given type.
-
-<!-- TODO: update above to say "introduces a name in the [value namespace]"
-    once namespaces are added. -->
+*Const generic parameters* allow items to be generic over constant values.
+The const identifier introduces a name in the [value namespace] for the constant parameter, and all instances of the item must be instantiated with a value of the given type.
 
 The only allowed types of const parameters are `u8`, `u16`, `u32`, `u64`, `u128`, `usize`,
 `i8`, `i16`, `i32`, `i64`, `i128`, `isize`, `char` and `bool`.
@@ -282,6 +278,7 @@ struct Foo<#[my_flexible_clone(unbounded)] H> {
 [slices]: ../types/slice.md
 [associated const]: associated-items.md#associated-constants
 [associated type]: associated-items.md#associated-types
+[attributes]: ../attributes.md
 [block]: ../expressions/block-expr.md
 [const contexts]: ../const_eval.md#const-context
 [const expression]: ../const_eval.md#constant-expressions
@@ -307,4 +304,4 @@ struct Foo<#[my_flexible_clone(unbounded)] H> {
 [type aliases]: type-aliases.md
 [type]: ../types.md
 [unions]: unions.md
-[attributes]: ../attributes.md
+[value namespace]: ../names/namespaces.md
diff --git a/src/names/namespaces.md b/src/names/namespaces.md
index 36b2e1026..225c46201 100644
--- a/src/names/namespaces.md
+++ b/src/names/namespaces.md
@@ -5,9 +5,6 @@ into separate namespaces based on the kind of entity the name refers to.
 Namespaces allow the occurrence of a name in one namespace to not conflict
 with the same name in another namespace.
 
-Within a namespace, names are organized in a hierarchy, where each level of
-the hierarchy has its own collection of named entities.
-
 There are several different namespaces that each contain different kinds of
 entities. The usage of a name will look for the declaration of that name in
 different namespaces, based on the context, as described in the [name
diff --git a/src/paths.md b/src/paths.md
index dbc73c4fa..46d0d4fae 100644
--- a/src/paths.md
+++ b/src/paths.md
@@ -1,10 +1,7 @@
 # Paths
 
-A *path* is a sequence of one or more path segments _logically_ separated by
-a namespace <span class="parenthetical">qualifier (`::`)</span>. If a path
-consists of only one segment, it refers to either an [item] or a [variable] in
-a local control scope. If a path has multiple segments, it always refers to an
-item.
+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].
 
 Two examples of simple paths consisting of only identifier segments:
 
@@ -25,7 +22,7 @@ x::y::z;
 > _SimplePathSegment_ :\
 > &nbsp;&nbsp; [IDENTIFIER] | `super` | `self` | `crate` | `$crate`
 
-Simple paths are used in [visibility] markers, [attributes], [macros], and [`use`] items.
+Simple paths are used in [visibility] markers, [attributes], [macros][mbe], and [`use`] items.
 Examples:
 
 ```rust
@@ -401,8 +398,7 @@ mod without { // crate::without
 [_TypeNoBounds_]: types.md#type-expressions
 [_TypeParamBounds_]: trait-bounds.md
 [literal]: expressions/literal-expr.md
-[item]: items.md
-[variable]: variables.md
+[items]: items.md
 [implementations]: items/implementations.md
 [use declarations]: items/use-declarations.md
 [IDENTIFIER]: identifiers.md
@@ -411,8 +407,10 @@ mod without { // crate::without
 [expressions]: expressions.md
 [extern prelude]: names/preludes.md#extern-prelude
 [macro transcribers]: macros-by-example.md
-[macros]: macros-by-example.md
+[macros]: macros.md
+[mbe]: macros-by-example.md
 [patterns]: patterns.md
 [trait implementations]: items/implementations.md#trait-implementations
 [traits]: items/traits.md
+[types]: types.md
 [visibility]: visibility-and-privacy.md

From 528b1a28a820227c62ca1ab8d712c31a401147a6 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Mon, 28 Jun 2021 16:15:05 -0700
Subject: [PATCH 03/12] Try to elaborate more on what Self defines.

---
 src/paths.md | 34 ++++++++++++++++++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)

diff --git a/src/paths.md b/src/paths.md
index 46d0d4fae..a628a5b07 100644
--- a/src/paths.md
+++ b/src/paths.md
@@ -221,10 +221,19 @@ impl S {
 
 ### `Self`
 
-`Self`, with a capital "S", is used to refer to the implementing type within
-[traits] and [implementations].
+`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.
+  When implementing a tuple or unit [struct], [enumeration], or [union], 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.
+  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. -->
 
 `Self` can only be used as the first segment, without a preceding `::`.
+The `Self` path cannot include generic arguments (as in `Self::<i32>`).
 
 ```rust
 trait T {
@@ -246,6 +255,20 @@ impl T for S {
         Self::C                  // `Self::C` is the constant value `9`.
     }
 }
+
+// `Self` is in scope within the generics of a trait definition,
+// to refer to the defining type.
+trait Add<Rhs = Self> {
+    type Output;
+    // `Self` can also reference associated items of the implementing types.
+    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).
+    tail: Option<Box<NonEmptyList<T>>>,
+}
 ```
 
 ### `super`
@@ -404,13 +427,20 @@ mod without { // crate::without
 [IDENTIFIER]: identifiers.md
 [`use`]: items/use-declarations.md
 [attributes]: attributes.md
+[enumeration]: items/enumerations.md
 [expressions]: expressions.md
 [extern prelude]: names/preludes.md#extern-prelude
+[implementation]: items/implementations.md
 [macro transcribers]: macros-by-example.md
 [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
 [traits]: items/traits.md
 [types]: types.md
+[union]: items/unions.md
+[value namespace]: names/namespaces.md
 [visibility]: visibility-and-privacy.md

From 9fbd6f05a08334a6cce24c7e2f1d66e800f25add Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Wed, 30 Jun 2021 17:40:13 -0700
Subject: [PATCH 04/12] Update `use` chapter with more detail.

This attempts to update the `use` chapter to explain the kinds of paths
and syntax it supports in more detail. This is not an exhaustive
explanation of resolution, and there are several things it does not
cover.
---
 src/items/use-declarations.md | 318 ++++++++++++++++++++++++++++------
 src/names/namespaces.md       |   2 -
 2 files changed, 261 insertions(+), 59 deletions(-)

diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md
index e2e202776..6df72fe1e 100644
--- a/src/items/use-declarations.md
+++ b/src/items/use-declarations.md
@@ -13,6 +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".
 
 [path]: ../paths.md
 [modules]: modules.md
@@ -21,7 +22,7 @@ and [blocks], usually at the top.
 Use declarations support a number of convenient shortcuts:
 
 * Simultaneously binding a list of paths with a common prefix, using the
-  glob-like brace syntax `use a::b::{c, d, e::f, g::h::i};`
+  brace syntax `use a::b::{c, d, e::f, g::h::i};`
 * Simultaneously binding a list of paths with a common prefix and their common
   parent module, using the `self` keyword, such as `use a::b::{self, c, d::e};`
 * Rebinding the target name as a new local name, using the syntax `use p::q::r
@@ -87,75 +88,186 @@ In this example, the module `quux` re-exports two public names defined in
 
 ## `use` Paths
 
-> **Note**: This section is incomplete.
+The [paths] that are allowed in a `use` item follow the [_SimplePath_] grammar and are similar to the paths that may be used in an expression.
+They may create bindings for:
 
-Some examples of what will and will not work for `use` items:
-<!-- Note: This example works as-is in either 2015 or 2018. -->
+* Nameable [items]
+* [Enum variants]
+* [Built-in types]
+* [Attributes]
+* [Derive macros]
 
-```rust
-# #![allow(unused_imports)]
-use std::path::{self, Path, PathBuf};  // good: std is a crate name
-use crate::foo::baz::foobaz;    // good: foo is at the root of the crate
+They cannot import [associated items], [generic parameters], [local variables], paths with [`Self`], or [tool attributes]. More restrictions are described below.
 
-mod foo {
+`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.
+For example, the following illustrates creating bindings for the same name in two namespaces:
 
-    pub mod example {
-        pub mod iter {}
-    }
-
-    use crate::foo::example::iter; // good: foo is at crate root
-//  use example::iter;      // bad in 2015 edition: relative paths are not allowed without `self`; good in 2018 edition
-    use self::baz::foobaz;  // good: self refers to module 'foo'
-    use crate::foo::bar::foobar;   // good: foo is at crate root
+```rust
+mod stuff {
+    pub struct Foo(pub i32);
+}
 
-    pub mod bar {
-        pub fn foobar() { }
-    }
+// Imports the `Foo` type and the `Foo` constructor.
+use stuff::Foo;
 
-    pub mod baz {
-        use super::bar::foobar; // good: super refers to module 'foo'
-        pub fn foobaz() { }
-    }
+fn example() {
+    let ctor = Foo;  // From value namespace
+    let x: Foo = ctor(123);
 }
-
-fn main() {}
 ```
 
-> **Edition Differences**: In the 2015 edition, `use` paths also allow
-> accessing items in the crate root. Using the example above, the following
-> `use` paths work in 2015 but not 2018:
+> **Edition Differences**: In the 2015 edition, `use` paths are relative from the crate root.
+> For example:
 >
 > ```rust,edition2015
-> # mod foo {
-> #     pub mod example { pub mod iter {} }
-> #     pub mod baz { pub fn foobaz() {} }
-> # }
-> use foo::example::iter;
-> use ::foo::baz::foobaz;
+> mod foo {
+>     pub mod example { pub mod iter {} }
+>     pub mod baz { pub fn foobaz() {} }
+> }
+> mod bar {
+>     // Resolves `foo` from the crate root.
+>     use foo::example::iter;
+>     // :: prefix explicitly resolves `foo` from the crate root.
+>     use ::foo::baz::foobaz;
+> }
+>
 > # fn main() {}
 > ```
 >
 > The 2015 edition does not allow use declarations to reference the [extern prelude].
-> Thus [`extern crate`] declarations are still required in 2015 to
-> reference an external crate in a use declaration. Beginning with the 2018
-> edition, use declarations can specify an external crate dependency the same
-> way `extern crate` can.
->
-> In the 2018 edition, if an in-scope item has the same name as an external
-> crate, then `use` of that crate name requires a leading `::` to
-> unambiguously select the crate name. This is to retain compatibility with
-> potential future changes. <!-- uniform_paths future-proofing -->
->
-> ```rust
-> // use std::fs; // Error, this is ambiguous.
-> use ::std::fs;  // Imports from the `std` crate, not the module below.
-> use self::std::fs as self_fs;  // Imports the module below.
->
-> mod std {
->     pub mod fs {}
-> }
-> # fn main() {}
-> ```
+> Thus, [`extern crate`] declarations are still required in 2015 to reference an external crate in a `use` declaration.
+> Beginning with the 2018 edition, `use` declarations can specify an external crate dependency the same way `extern crate` can.
+
+## `as` renames
+
+The `as` keyword can be used to change the name of an imported entity.
+For example:
+
+```rust
+// Creates a non-public alias `bar` for the function `foo`.
+use inner::foo as bar;
+
+mod inner {
+    pub fn foo() {}
+}
+```
+
+## 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 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
+use std::collections::{BTreeSet, hash_map::{self, HashMap}};
+```
+
+An empty brace does not import anything. `a::b::{}` is treated as `a::b::{self as _}` and `use {};` has no effect.
+
+> **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.
+
+```rust
+mod stuff {
+    pub fn foo() {}
+    pub fn bar() {}
+}
+mod example {
+    // Creates a binding for `stuff` and `foo`.
+    use crate::stuff::{self, foo};
+    pub fn baz() {
+        foo();
+        stuff::bar();
+    }
+}
+# fn main() {}
+```
+
+`self` only creates a binding from the [type namespace] of the parent entity.
+For example, in the following, only the `foo` mod is imported:
+
+```rust,compile_fail
+mod bar {
+    pub mod foo {}
+    pub fn foo() {}
+}
+
+// This only imports the module `foo`. The function `foo` lives in
+// the value namespace and is not imported.
+use bar::foo::{self};
+
+fn main() {
+    foo(); // Error, `foo` is a module
+}
+```
+
+> **Note**: `self` as the first segment of a `use` path has a different meaning from `self` inside braces.
+> See [`self`] in the paths chapter for more information no the meaning of a leading `self`.
+
+## Glob imports
+
+The `*` character may be used as the last segment of a `use` path to import all importable entities from the entity of the preceding segment.
+For example:
+
+```rust
+// Creates a non-public alias to `bar`.
+use foo::*;
+
+mod foo {
+    fn i_am_private() {}
+    enum Example {
+        V1,
+        V2,
+    }
+    pub fn bar() {
+        // Creates local aliases to V1 and V2 of the Example enum.
+        use Example::*;
+        let x = V1;
+    }
+}
+```
+
+Items and named imports are allowed to shadow names from glob imports in the same [namespace].
+That is, if there is a name already defined by another item in the same namespace, the glob import will skip it.
+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.
+//
+// Note that the order of definition here is unimportant.
+use clashing::*;
+struct Foo {
+    field: f32,
+}
+
+fn do_stuff() {
+    // Uses the constructor from clashing::Foo
+    let f1 = Foo(123);
+    // The struct expression uses the type from the Foo struct defined above.
+    let f2 = Foo { field: 1.0 };
+    // Also imported from the glob import.
+    let z = Bar {};
+}
+
+mod clashing {
+    pub struct Foo(pub i32);
+    pub struct Bar {}
+}
+```
+
+`*` 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.
+> This cannot be used in the crate root itself.
 
 ## Underscore Imports
 
@@ -201,8 +313,100 @@ m!(use std as _;);
 // use std as _;
 ```
 
-[IDENTIFIER]: ../identifiers.md
+## Restrictions
+
+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`.
+* 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:
+  ```rust,compile_fail
+  enum MyEnum {
+      MyVariant
+  }
+  type TypeAlias = MyEnum;
+
+  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.
+
+Glob imports are allowed to import conflicting names in the same namespaces as long as the name is not used or shadowed.
+Example:
+
+```rust
+mod foo {
+    pub struct Qux;
+}
+
+mod bar {
+    pub struct Qux;
+}
+
+use foo::*;
+use bar::*; // Ok, no name conflict.
+
+fn main() {
+    // This would be an error, due to the ambiguity.
+    // let x = Qux;
+}
+```
+
+Multiple glob imports are allowed to import the same name if the imports are of the same item (following re-exports). The visibility of the name is the maximum visibility of the imports. Example:
+
+```rust
+mod foo {
+    pub struct Qux;
+}
+
+mod bar {
+    pub use super::foo::Qux;
+}
+
+// These both import the same `Qux`.
+// The visibility of `Qux` is `pub` because that is the maximum
+// visibility between these two `use` declarations.
+use foo::*;
+pub use bar::*;
+# fn main() {}
+```
+
+If an in-scope item has the same name as a crate name in the [extern prelude], then `use` of that crate name requires a leading `::` to unambiguously select the crate name or `crate::` to use the item from the crate root.
+
+```rust,compile_fail
+use std::fs; // Error, this is ambiguous.
+
+mod std {
+    pub mod fs {}
+}
+# fn main() {}
+```
+
+
 [_SimplePath_]: ../paths.md#simple-paths
 [`extern crate`]: extern-crates.md
+[`macro_rules`]: ../macros-by-example.md
+[`self`]: ../paths.md#self
+[associated items]: associated-items.md
+[Attributes]: ../attributes.md
+[Built-in types]: ../types.md
+[Derive macros]: ../procedural-macros.md#derive-macros
+[Enum variants]: enumerations.md
 [extern prelude]: ../names/preludes.md#extern-prelude
-[path qualifiers]: ../paths.md#path-qualifiers
+[generic parameters]: generics.md
+[IDENTIFIER]: ../identifiers.md
+[items]: ../items.md
+[local variables]: ../variables.md
+[namespace]: ../names/namespaces.md
+[namespaces]: ../names/namespaces.md
+[paths]: ../paths.md
+[tool attributes]: ../attributes.md#tool-attributes
+[type alias]: type-aliases.md
+[type namespace]: ../names/namespaces.md
diff --git a/src/names/namespaces.md b/src/names/namespaces.md
index 225c46201..b27511eb3 100644
--- a/src/names/namespaces.md
+++ b/src/names/namespaces.md
@@ -100,8 +100,6 @@ A [use declaration] has named aliases that it imports into scope, but the
 introduce aliases into multiple namespaces, depending on the item kind being
 imported.
 
-<!-- TODO: describe how `use` works on the use-declarations page, and link to it here. -->
-
 ## Sub-namespaces
 
 The macro namespace is split into two sub-namespaces: one for [bang-style macros] and one for [attributes].

From 94cce7553eb9ecb37296c16b9d5929531bb2c73f Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Fri, 2 Jul 2021 11:35:24 -0700
Subject: [PATCH 05/12] Fixes from review.

---
 src/items/enumerations.md     |  9 ++++++---
 src/items/use-declarations.md | 12 +++++++-----
 src/paths.md                  |  2 +-
 3 files changed, 14 insertions(+), 9 deletions(-)

diff --git a/src/items/enumerations.md b/src/items/enumerations.md
index 043cbe962..90158c934 100644
--- a/src/items/enumerations.md
+++ b/src/items/enumerations.md
@@ -82,11 +82,12 @@ enum Enum {
 ```
 
 Variant constructors are similar to [struct] definitions, and can be referenced by a path from the enumeration name, including in [use declarations].
-The constructors are defined in both the [type namespace] and [value namespace] within the enumeration.
+Each variant defines its type in the [type namespace], though that type cannot be used as a type specifier.
+Each variant also defines a constructor in the [value namespace].
 
 A struct-like variant can be instantiated with a [struct expression].
-A tuple-like variant can be instantiated with a [call expression].
-A unit-like variant can be instantiated with a [path expression].
+A tuple-like variant can be instantiated with a [call expression] or a [struct expression].
+A unit-like variant can be instantiated with a [path expression] or a [struct expression].
 For example:
 
 ```rust
@@ -98,7 +99,9 @@ enum Examples {
 
 use Examples::*; // Creates aliases to all variants.
 let x = UnitLike; // Path expression of the const item.
+let x = UnitLike {}; // Struct expression.
 let y = TupleLike(123); // Call expression.
+let y = TupleLike { 0: 123 }; // Struct expression using integer field names.
 let z = StructLike { value: 123 }; // Struct expression.
 ```
 
diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md
index 6df72fe1e..9964ca368 100644
--- a/src/items/use-declarations.md
+++ b/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".
+A `use` declaration is also sometimes called an _import_ or if it is public it is a _re-export_.
 
 [path]: ../paths.md
 [modules]: modules.md
@@ -165,7 +165,8 @@ Braces can be nested, creating a tree of paths, where each grouping of segments
 use std::collections::{BTreeSet, hash_map::{self, HashMap}};
 ```
 
-An empty brace does not import anything. `a::b::{}` is treated as `a::b::{self as _}` and `use {};` has no effect.
+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 -->
 
 > **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.
 
@@ -207,8 +208,9 @@ fn main() {
 }
 ```
 
-> **Note**: `self` as the first segment of a `use` path has a different meaning from `self` inside braces.
-> See [`self`] in the paths chapter for more information no the meaning of a leading `self`.
+> **Note**: `self` may also be used as the first segment of a path.
+> The usage of `self` as the first segment and inside a `use` brace is logically the same; it means the current module of the parent segment, or the current module if there is no parent segment.
+> See [`self`] in the paths chapter for more information on the meaning of a leading `self`.
 
 ## Glob imports
 
@@ -234,7 +236,7 @@ mod foo {
 ```
 
 Items and named imports are allowed to shadow names from glob imports in the same [namespace].
-That is, if there is a name already defined by another item in the same namespace, the glob import will skip it.
+That is, if there is a name already defined by another item in the same namespace, the glob import will be shadowed.
 For example:
 
 ```rust
diff --git a/src/paths.md b/src/paths.md
index a628a5b07..5b065c164 100644
--- a/src/paths.md
+++ b/src/paths.md
@@ -225,7 +225,7 @@ impl S {
 
 * In a [trait] definition, it refers to the type implementing the trait.
 * In an [implementation], it refers to the implementing type.
-  When implementing a tuple or unit [struct], [enumeration], or [union], it also refers to the constructor in the [value namespace].
+  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.
   The definition is not allowed to be infinitely recursive (there must be an indirection).
 

From 30d7bfc4c73023bf4d173cea70b711f712c1d375 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Sun, 4 Jul 2021 20:41:35 -0700
Subject: [PATCH 06/12] Fix mistake in Self.

---
 src/paths.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/paths.md b/src/paths.md
index 5b065c164..26acd489d 100644
--- a/src/paths.md
+++ b/src/paths.md
@@ -267,7 +267,7 @@ trait Add<Rhs = Self> {
 struct NonEmptyList<T> {
     head: T,
     // A struct can reference itself (as long as it is not infinitely recursive).
-    tail: Option<Box<NonEmptyList<T>>>,
+    tail: Option<Box<Self>>,
 }
 ```
 

From 127e560346d1586480d5d409ef5db88cccddcf35 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Sun, 30 Jun 2024 10:24:58 -0700
Subject: [PATCH 07/12] Remove ambiguity error removed in Rust 1.72.

This was changed in https://github.com/rust-lang/rust/issues/56414
to favor in-scope items.
---
 src/items/use-declarations.md | 12 ------------
 1 file changed, 12 deletions(-)

diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md
index 9964ca368..c17c6f046 100644
--- a/src/items/use-declarations.md
+++ b/src/items/use-declarations.md
@@ -380,18 +380,6 @@ pub use bar::*;
 # fn main() {}
 ```
 
-If an in-scope item has the same name as a crate name in the [extern prelude], then `use` of that crate name requires a leading `::` to unambiguously select the crate name or `crate::` to use the item from the crate root.
-
-```rust,compile_fail
-use std::fs; // Error, this is ambiguous.
-
-mod std {
-    pub mod fs {}
-}
-# fn main() {}
-```
-
-
 [_SimplePath_]: ../paths.md#simple-paths
 [`extern crate`]: extern-crates.md
 [`macro_rules`]: ../macros-by-example.md

From 163f7bc1cc436a1bfa8b9327f7e7a076d87b06d9 Mon Sep 17 00:00:00 2001
From: Travis Cross <tc@traviscross.com>
Date: Fri, 5 Jul 2024 21:27:45 +0000
Subject: [PATCH 08/12] Make some editorial improvements

We've merged PR #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          |  2 +-
 src/items/static-items.md     |  2 +-
 src/items/structs.md          |  2 +-
 src/items/traits.md           |  4 +--
 src/items/type-aliases.md     |  2 +-
 src/items/use-declarations.md | 65 ++++++++++++++++++-----------------
 src/paths.md                  | 23 +++++++------
 7 files changed, 52 insertions(+), 48 deletions(-)

diff --git a/src/items/modules.md b/src/items/modules.md
index 375cf2b56..e709f52fd 100644
--- a/src/items/modules.md
+++ b/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.
 
diff --git a/src/items/static-items.md b/src/items/static-items.md
index ee93b931e..343d30cbe 100644
--- a/src/items/static-items.md
+++ b/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.
diff --git a/src/items/structs.md b/src/items/structs.md
index 36d49e634..e59d7e9c0 100644
--- a/src/items/structs.md
+++ b/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:
diff --git a/src/items/traits.md b/src/items/traits.md
index 677199fc8..cb6c6f902 100644
--- a/src/items/traits.md
+++ b/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
diff --git a/src/items/type-aliases.md b/src/items/type-aliases.md
index 5699298d5..ef3e6fcb7 100644
--- a/src/items/type-aliases.md
+++ b/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:
diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md
index c17c6f046..46b56fcb7 100644
--- a/src/items/use-declarations.md
+++ b/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;
 }
 ```
 
diff --git a/src/paths.md b/src/paths.md
index 26acd489d..cd54463a4 100644
--- a/src/paths.md
+++ b/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

From 9ec720bafde4dd095a4296083777d277b3f30633 Mon Sep 17 00:00:00 2001
From: Travis Cross <tc@traviscross.com>
Date: Fri, 5 Jul 2024 21:34:52 +0000
Subject: [PATCH 09/12] Note a redundantly imported name is allowed to be used

We had mentioned and demonstrated that a name is allowed to be
redundantly imported by multiple glob imports, but we hadn't said
that it is allowed to then be *used*.

Given the example that directly proceeds this, it seems important to
make a note of that, so let's do that, and let's extend the example to
demonstrate this.
---
 src/items/use-declarations.md | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md
index 46b56fcb7..83d6f1121 100644
--- a/src/items/use-declarations.md
+++ b/src/items/use-declarations.md
@@ -364,7 +364,7 @@ fn main() {
 }
 ```
 
-Multiple glob imports are allowed to import the same name if the imports are of the same item (following re-exports). The visibility of the name is the maximum visibility of the imports. Example:
+Multiple glob imports are allowed to import the same name, and that name is allowed to be used, if the imports are of the same item (following re-exports). The visibility of the name is the maximum visibility of the imports. Example:
 
 ```rust
 mod foo {
@@ -375,12 +375,15 @@ mod bar {
     pub use super::foo::Qux;
 }
 
-// These both import the same `Qux`.
-// The visibility of `Qux` is `pub` because that is the maximum
-// visibility between these two `use` declarations.
-use foo::*;
+// These both import the same `Qux`. The visibility of `Qux`
+// is `pub` because that is the maximum visibility between
+// these two `use` declarations.
 pub use bar::*;
-# fn main() {}
+use foo::*;
+
+fn main() {
+    let _: Qux = Qux;
+}
 ```
 
 [_SimplePath_]: ../paths.md#simple-paths

From da258351b19000545d6873d171261084a47d7135 Mon Sep 17 00:00:00 2001
From: Travis Cross <tc@traviscross.com>
Date: Sat, 6 Jul 2024 03:06:27 +0000
Subject: [PATCH 10/12] Remove "or shadowed" caveat

The claim here was that:

> Glob imports are allowed to import conflicting names in the same
> namespace as long as the name is not used *or shadowed*.

It's true that the name being used will cause an error.  But it's not
true that the name being shadowed will cause one, so let's remove
that part.
---
 src/items/use-declarations.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md
index 83d6f1121..6299177a5 100644
--- a/src/items/use-declarations.md
+++ b/src/items/use-declarations.md
@@ -343,7 +343,7 @@ The following are restrictions for valid `use` declarations:
 
 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 namespace 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.
 Example:
 
 ```rust

From 65c20b18bc2bb07c666f58cb1232276f0835fd1f Mon Sep 17 00:00:00 2001
From: Travis Cross <tc@traviscross.com>
Date: Sat, 6 Jul 2024 03:16:46 +0000
Subject: [PATCH 11/12] Replace "Example:" with "For example:"

It's a bit more common throughout the Reference, including even within
this PR, to say "For example:" rather than just "Example:", and it's
more grammatically regular, so let's fix up the ones that went the
other way in this branch.
---
 src/items/use-declarations.md | 6 +++---
 src/paths.md                  | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md
index 6299177a5..4e1096082 100644
--- a/src/items/use-declarations.md
+++ b/src/items/use-declarations.md
@@ -326,7 +326,7 @@ The following are restrictions for valid `use` declarations:
 * `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:
+* `use` paths cannot refer to enum variants through a [type alias]. For example:
   ```rust,compile_fail
   enum MyEnum {
       MyVariant
@@ -344,7 +344,7 @@ The following are restrictions for valid `use` declarations:
 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 namespace as long as the name is not used.
-Example:
+For example:
 
 ```rust
 mod foo {
@@ -364,7 +364,7 @@ fn main() {
 }
 ```
 
-Multiple glob imports are allowed to import the same name, and that name is allowed to be used, if the imports are of the same item (following re-exports). The visibility of the name is the maximum visibility of the imports. Example:
+Multiple glob imports are allowed to import the same name, and that name is allowed to be used, if the imports are of the same item (following re-exports). The visibility of the name is the maximum visibility of the imports. For example:
 
 ```rust
 mod foo {
diff --git a/src/paths.md b/src/paths.md
index cd54463a4..525a325e5 100644
--- a/src/paths.md
+++ b/src/paths.md
@@ -23,7 +23,7 @@ x::y::z;
 > &nbsp;&nbsp; [IDENTIFIER] | `super` | `self` | `crate` | `$crate`
 
 Simple paths are used in [visibility] markers, [attributes], [macros][mbe], and [`use`] items.
-Examples:
+For example:
 
 ```rust
 use std::io::{self, Write};

From 585407f04bba5d154342ff305b3385bc555d1468 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Fri, 26 Jul 2024 10:02:58 -0700
Subject: [PATCH 12/12] Remove struct-like enum variant values.

These were removed in https://github.com/rust-lang/rust/pull/103578.
---
 src/items/enumerations.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/items/enumerations.md b/src/items/enumerations.md
index 90158c934..5f008461a 100644
--- a/src/items/enumerations.md
+++ b/src/items/enumerations.md
@@ -83,7 +83,7 @@ enum Enum {
 
 Variant constructors are similar to [struct] definitions, and can be referenced by a path from the enumeration name, including in [use declarations].
 Each variant defines its type in the [type namespace], though that type cannot be used as a type specifier.
-Each variant also defines a constructor in the [value namespace].
+Tuple-like and unit-like variants also define a constructor in the [value namespace].
 
 A struct-like variant can be instantiated with a [struct expression].
 A tuple-like variant can be instantiated with a [call expression] or a [struct expression].