Expand name resolution stub

Author: yaahc

src/macros-by-example.md

@@ -326,6 +326,13 @@ fn foo() {
 // m!(); // Error: m is not in scope.
 ```
 
+* textual scope name bindings for macros may shadow path-based scope bindings
+  to macros
+    * (the later may be unresolved, in which case it doesn't matter if it's a
+      macro, e.g. you could have an invalid import with the same name as a
+      valid macro resolution via textual scope and the textual scope macro will
+      shadow the invalid import) TODO: do we care to document this?
+
 r[macro.decl.scope.macro_use]
 ### The `macro_use` attribute
 

src/names/name-resolution.md

@@ -1,4 +1,116 @@
+r[names.resolution]
 # Name resolution
 
-> [!NOTE]
-> This is a placeholder for future expansion.
+r[names.resolution.intro]
+
+_Name resolution_ is the process of tying paths and other identifiers to the
+declarations of those entities. Names are segregated into different
+[namespaces], allowing entities in different namespaces to share the same name
+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".
+* Associated consts and functions, methods, and enum variants are resolved during type checking.
+    * This stage of resolution is known as type dependent 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]
+
+* 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 (as of 2018 edition i think, pretty sure this applies specifically to path-based scope for macros)
+* 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.
+
+r[names.resolution.early.imports]
+
+* 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.
+
+r[names.resolution.early.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.reserved-names]
+
+the names cfg and cfg_attr are reserved in the macro attribute sub-namespace
+
+* https://doc.rust-lang.org/nightly/reference/names/namespaces.html#r-names.namespaces.sub-namespaces
+
+r[names.resolution.early.imports.errors.ambiguity]
+
+* How does this relate to? https://doc.rust-lang.org/nightly/reference/items/use-declarations.html#ambiguities
+    * Note that shadowing is an exception
+    * Fill out the documentation for shadowing and ambiguity alongside these items, link to them in the name resolution chapter
+
+* shadowing and ambiguity may or may not represent the same section or one may be a subsection of the other
+
+r[names.resolution.early.imports.errors.ambiguity.builtin-attr]
+* it is an error to have a user defined attribute or derive macro with the same name as a builtin attribute (e.g. inline)
+r[names.resolution.early.imports.errors.ambiguity.derivehelper]
+* derive helpers used before their associated derive may not shadow other attributes or other derive helpers that are otherwise in scope after their derive
+r[names.resolution.early.imports.errors.ambiguity.textualvspathbasedscope]
+* path-based scope bindings for macros may not shadow textual scope bindings to macros
+* https://doc.rust-lang.org/nightly/reference/names/namespaces.html#r-names.namespaces.sub-namespaces.use-shadow
+r[names.resolution.early.imports.errors.ambiguity.globvsouter]
+* it is an error to shadow an outer name binding with a glob import
+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
+        * this is still an error even if there is a third non glob binding resolution to an item with the same name
+* it is not an error to have two glob imports which include items which would be ambiguous so long as you do not name one of those items through the ambiguous glob imports
+r[names.resolution.early.imports.errors.ambiguity.globvsexpanded]
+    * Grey Area
+r[names.resolution.early.imports.errors.ambiguity.moreexpandedvsouter]
+    * it is an error for name bindings from macro expansions to shadow name bindings from outside of those expansions
+
+r[names.resolution.early.macros]
+
+* .visitation-order
+    * derive helpers
+        * not visited when resolving derive macros in the parent scope (starting scope)
+    * derive helpers compat
+        * always visited
+    * macro rules bindings (textual scope macros)
+        * always visited
+    * modules (path-based scope macros)
+        * always visited
+    * macrouseprelude
+        * not visited in 2018 and later when `#[no_implicit_prelude]` is present
+    * stdlibprelude
+        * always visited for macro resolutions
+    * builtinattrs
+        * always visited
+* .subnamespaces
+    * 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.late]
+
+r[names.resolution.type-dependent]
+
+[use glob shadowing]: ../items/use-declarations.md#items.use.glob.shadowing
+[Macros]: ../macros.md
+[use declarations]: ../items/use-declarations.md
+[macro textual scope shadowing]: ../macros-by-example.md#macro.decl.scope.textual.shadow
+[`let` bindings]: ../statements.md#let-statements
+[item definitions]: ../items.md
+[namespaces]: ../names/namespaces.md
+[scope]: ../names/scopes.md
+[visibility]: ../visibility-and-privacy.md