rewrite bullet points as prose

Author: yaahc

src/items/use-declarations.md

@@ -396,9 +396,11 @@ r[items.use.ambiguities]
 > This section is incomplete.
 
 r[items.use.ambiguities.intro]
-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.
+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 where neither import is
+[permitted](names.resolution.expansion.imports.shadowing) to shadow the other.
 
-* except where shadowing is allowed
 r[names.resolution.early.imports.errors.ambiguity.globvsglob]
 * it is an error to name an item through ambiguous use declarations
     * two globs imports which both have an item matching that name where the items are different
@@ -409,6 +411,11 @@ r[items.use.ambiguities.glob]
 Glob imports are allowed to import conflicting names in the same namespace as long as the name is not used.
 For example:
 
+TODO: move this section? It's documenting a situation that _isnt_ an ambiguity
+error. I've been working off of a pattern I think I saw in a few other
+locations, where we have specific error sections that document all of the
+reference relevant error cases associated with an some part of the language.
+
 ```rust
 mod foo {
     pub struct Qux;

src/names/name-resolution.md

@@ -10,54 +10,120 @@ without conflict. Each name is valid within a [scope], or a region of source
 text where that name may be referenced. Access to certain names may be
 restricted based on their [visibility].
 
-* Names are resolved at three different stages of compilation.
-* [Macros] and [use declarations] are resolved during macro expansion.
-    * This stage of resolution is known as "Early Resolution".
+Name resolution is split into three stages throughout the compilation process.
+The first stage, Expansion-time resolution, resolves all [use declarations] and
+[macro invocations]. The second stage, Primary resolution, resolves all names
+that have not yet been resolved that do not depend on type information to
+resolve. The last stage, Type-relative resolution, resolves the remaining names
+once type information is available.
+
+> Note
+>
+> * Expansion-time resolution is also known as "Early Resolution"
+> * Primary resolution is also known as "Late Resolution"
+
+r[names.resolution.expansion]
+## Expansion-time name resolution
+
+r[names.resolution.expansion.intro]
+
+Expansion-time name resolution is the stage of name resolution necessary to
+complete macro expansion and fully generate a crate's AST. This stage requires
+the resolution of macro invocations and use declarations. Resolving use
+declarations is required to resolve [path-based scope] macro invocations.
+Resolving macro invocations is required in order to expand them.
+
+The expansion process is iterative, alternately resolving imports, resolving
+and expanding macro invocations, then repeating until there are no further
+macros invocations to resolve. Once this process is completed all the imports
+are resolved again to ensure that the macro expansion process did not introduce
+any new ambiguious imports.
+
+TODO: do we want to talk about this? feels like an implementation detail but
+also really helps to understand certain kinds of ambiguity errors that users
+can run into.
+
+> Note
+>
+> This causes so called time traveling ambiguities, such as when a glob import introduces an item that is ambiguous with its own base path.
+>
+```rust
+macro_rules! m {
+    () => { mod bar {} }
+}
+
+mod foo {
+    pub mod bar {
+        pub(crate) use m;
+    }
+}
+
+fn f() {
+    use foo::*;
+    // * initially speculatively resolve bar from foo via glob import
+    // * expansion of m introduces a second bar module
+    // * expansion-time resolution finalizes resolutions by re-resolving all
+    //   imports and macro invocations, sees the introduced ambiguity
+    //   and reports it as an error
+    bar::m!(); // ERROR `bar` is ambiguous
+}
+```
+
+TODO I would like to be able to link to a path-based scope section that
+     discusses the various kinds of macros that can be invoked via path-based scope.
+     Right now the section I know of off of the top of my head lives in the macros
+     by example chapter.
+
+r[names.resolution.expansion.imports]
+
+All use declarations are fully resolved during this stage of resolution.
+Type-relative paths cannot be resolved at this stage of compilation and will
+produce an error.
+
 * `Type::assoc_item`, `<Type>::assoc_item`, `<Enum>::Variant` and `EnumTyAlias::Variant` are resolved during type checking
     * `Trait::assoc_item`, `<Type as Trait>::assoc_item` and `Enum::Variant` are resolved during late resolution
-    * This stage of resolution is known as type-relative resolution.
-        * in reality this is never talked about so I doubt it has a name yet.
-* All other names are resolved during AST lowering.
-    * This stage of resolution is known as "Late Resolution".
-    * Note, late resolution occurs before type dependent resolution.
-
-r[names.resolution.early]
-## Early name resolution
 
-r[names.resolution.early.intro]
+```rust
+mod my_mod {
+    pub const Const: () = ();
 
-* early name resolution is the part of name resolution that happens during macro expansion
-* early name resolution includes the resolution of imports and macros
-* early name resolution is the minimum amount of resolution required to resolve macro invocations so they can be expanded.
-* resolving imports is necessary to resolve macro invocations
-    * specifically for path-based scope macro resolutions, this can occur
-      either because of a `#[macro_export]`, a proc macro definition, or a
-      reexport of a macro in 2018 or later code.
-* resolving macro invocations and tying them to macro declarations is necessary so they can be expanded
-* this process is iterative and repeats until there are no remaining unexpanded macro invocations (fixed point algorithm)
-* Post expansion these resolutions are checked again to ensure no new ambiguities were introduced by the expansion process
-  * This causes so called time traveling ambiguities, such as when a glob import introduces an item that is ambiguous with its own base path.
+    pub enum MyEnum {
+        MyVariant
+    }
 
-TODO Document some time traveling ambiguitie examples, place in relevant ambiguity section
+    impl MyEnum {
+        pub const Const: () = ();
+    }
 
-r[names.resolution.early.imports]
+    pub type TypeAlias = MyEnum;
+}
 
-* All imports are fully resolved at this point.
-    * imports of names that cannot be fully resolved during macro expansion, such as those depending on type information, are not supported and will produce an error.
+fn foo() {
+    use my_mod::MyEnum; // OK
+    use my_mod::MyEnum::MyVariant; // OK
+    use my_mod::TypeAlias; // OK
+    use my_mod::TypeAlias::MyVariant; // Doesn't work
+    use my_mod::MyEnum::Const; // Doesn't work
+    use my_mod::Const; // OK
+    let _ = my_mod::TypeAlias::MyVariant; // OK
+    let _ = my_mod::MyEnum::Const; // OK
+}
+```
 
-TODO example of unsupported type dependent import
-
-r[names.resolution.early.imports.shadowing]
+r[names.resolution.expansion.imports.shadowing]
 
 The following is a list of situations where shadowing of use declarations is permitted:
 
 * [use glob shadowing]
 * [macro textual scope shadowing]
 
-r[names.resolution.early.imports.errors]
-r[names.resolution.early.imports.errors.ambiguity]
+r[names.resolution.expansion.imports.errors]
+r[names.resolution.expansion.imports.errors.ambiguity]
+
+TODO shadowing and ambiguity may or may not represent the same section or one may be a subsection of the other
 
-* shadowing and ambiguity may or may not represent the same section or one may be a subsection of the other
+The following is a list of situations where shadowing of use declarations is
+_NOT_ permitted, otherwise known as ambiguity errors:
 
 * Builtin Attributes
 * Derive Helpers
@@ -67,7 +133,7 @@ r[names.resolution.early.imports.errors.ambiguity]
 * ~~Glob vs Expanded~~ pretty certain we don't want to mention this one
 * More Expanded vs Outer
 
-r[names.resolution.early.macros]
+r[names.resolution.expansion.macros]
 
 * .visitation-order
     * derive helpers
@@ -89,7 +155,7 @@ r[names.resolution.early.macros]
     * macros are split into two subnamespaces, one for bang macros, and the other for attributes and derives. Resolution candidates from the incorrect subnamespace are ignored
         * https://doc.rust-lang.org/nightly/reference/names/namespaces.html#r-names.namespaces.sub-namespaces
 
-r[names.resolution.early.macros.errors.reserved-names]
+r[names.resolution.expansion.macros.errors.reserved-names]
 
 the names cfg and cfg_attr are reserved in the macro attribute sub-namespace