WIP

Author: yaahc

src/items/use-declarations.md

@@ -303,6 +303,10 @@ mod clashing {
 }
 ```
 
+> [!NOTE]
+>
+> For areas where shadowing is not allowed, see [name resolution ambiguities].
+
 r[items.use.glob.last-segment-only]
 `*` cannot be used as the first or intermediate segments.
 
@@ -390,10 +394,6 @@ r[items.use.restrictions.variant]
   use TypeAlias::MyVariant; //~ ERROR
   ```
 
-TODO mention ambiguities and link to name-res. Moved to name-res because
-ambiguities are fundamentally a product of the place of use, not the use
-declaration.
-
 [`extern crate`]: extern-crates.md
 [`macro_rules`]: ../macros-by-example.md
 [`self`]: ../paths.md#self
@@ -412,3 +412,4 @@ declaration.
 [tool attributes]: ../attributes.md#tool-attributes
 [type alias]: type-aliases.md
 [type namespace]: ../names/namespaces.md
+[name resolution ambiguities]: ../names/name-resolution.html#r-names.resolution.expansion.imports.errors.ambiguity

src/names/name-resolution.md

@@ -132,20 +132,13 @@ _NOT_ permitted, otherwise known as ambiguity errors:
 r[names.resolution.expansion.imports.errors.ambiguity]
 ## Ambiguities
 
-r[items.use.ambiguities.intro]
+r[names.resolution.expansion.imports.errors.ambiguity.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 where neither import is
 [permitted] to shadow the other.
 
-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 not an error even if 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
-    * Should this live alongside use decls item page or in the name resolution page?
-
-r[items.use.ambiguities.glob]
+r[names.resolution.expansion.imports.errors.ambiguity.glob]
 Glob imports are allowed to import conflicting names in the same namespace as
 long as the name is not used. Names may not be resolved through ambiguous glob
 statements. Conflicting names from ambiguous glob statements may still be
@@ -200,87 +193,6 @@ fn main() {
 }
 ```
 
-r[names.resolution.early.imports.errors.ambiguity.builtin-attr]
-It is an error to use a user defined attribute or derive macro with the same
-name as a builtin attribute (e.g. inline)
-* I think we may special case this one and allow certain kinds of ambiguities
-  where the builtin-attr is shadowed by a user attribute (not sure if this
-  actually exists or is just proposed, TODO investigate)
-
-<!-- ignore: test doesn't support proc-macro -->
-```rust,ignore
-// myinline/src/lib.rs
-use proc_macro::TokenStream;
-
-#[proc_macro_attribute]
-pub fn inline(_attr: TokenStream, item: TokenStream) -> TokenStream {
-    item
-}
-```
-
-<!-- ignore: requires external crates -->
-```rust,ignore
-// src/lib.rs
-use myinline::inline;
-use myinline::inline as myinline;
-
-#[myinline::inline]
-pub fn foo() {}
-
-#[crate::inline]
-pub fn bar() {}
-
-#[myinline]
-pub fn baz() {}
-
-#[inline] // ERROR `inline` is ambiguous
-pub fn qux() {}
-```
-
-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
-    * TODO example? This ones harder to do concisely afaik
-
-Helper attributes may not be used before the macro that introduces them.
-
-* What happens if two macros introduce the same helper, will the second one not
-  be able to see the attribute of the first anymore, assuming their order is
-  "firstmacro" "helper" "secondmacro"?
-
-> [!NOTE]
-> rustc currently allows derive helpers to be used before their attribute macro
-> introduces them into scope so long as they do not shadow any other attributes
-> or derive helpers that are otherwise correctly in scope. This behavior
-> deprecated and slated for removal.
-> <!-- ignore: requires external crates -->
-> ```rust,ignore
-> #[helper] // deprecated, hard error in the future
-> #[derive(WithHelperAttr)]
-> struct Struct {
->     field: (),
-> }
-> ```
->
-> For more details, see [Rust issue #79202](https://github.com/rust-lang/rust/issues/79202).
-
-
-r[names.resolution.early.imports.errors.ambiguity.pathvstextualmacro]
-Path-based scope bindings for macros may not shadow textual scope bindings to macros.
-
-```rust,compile_fail
-#[macro_export]
-macro_rules! m2 {
-    () => {}
-}
-macro_rules! m {
-    () => {}
-}
-pub fn foo() {
-    m!(); // ERROR `m` is ambiguous
-    use crate::m2 as m; // in scope for entire function body
-}
-```
-
 r[names.resolution.early.imports.errors.ambiguity.globvsouter]
 it is an error to shadow an outer name binding with a glob import.
 
@@ -352,7 +264,7 @@ pub fn foo() {
 > }
 > ```
 
-r[macro.decl.scope.textual.ambiguity.moreexpandedvsouter]
+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
 
 ```rust,compile_fail
@@ -374,10 +286,89 @@ fn foo() {
 }
 ```
 
-
 r[names.resolution.early.imports.errors.ambiguity.globvsexpanded]
 * Grey Area
 
+r[names.resolution.early.imports.errors.ambiguity.pathvstextualmacro]
+Path-based scope bindings for macros may not shadow textual scope bindings to macros.
+
+```rust,compile_fail
+#[macro_export]
+macro_rules! m2 {
+    () => {}
+}
+macro_rules! m {
+    () => {}
+}
+pub fn foo() {
+    m!(); // ERROR `m` is ambiguous
+    use crate::m2 as m; // in scope for entire function body
+}
+```
+
+r[names.resolution.early.imports.errors.ambiguity.builtin-attr]
+It is an error to use a user defined attribute or derive macro with the same
+name as a builtin attribute (e.g. inline)
+* I think we may special case this one and allow certain kinds of ambiguities
+  where the builtin-attr is shadowed by a user attribute (not sure if this
+  actually exists or is just proposed, TODO investigate)
+
+<!-- ignore: test doesn't support proc-macro -->
+```rust,ignore
+// myinline/src/lib.rs
+use proc_macro::TokenStream;
+
+#[proc_macro_attribute]
+pub fn inline(_attr: TokenStream, item: TokenStream) -> TokenStream {
+    item
+}
+```
+
+<!-- ignore: requires external crates -->
+```rust,ignore
+// src/lib.rs
+use myinline::inline;
+use myinline::inline as myinline;
+
+#[myinline::inline]
+pub fn foo() {}
+
+#[crate::inline]
+pub fn bar() {}
+
+#[myinline]
+pub fn baz() {}
+
+#[inline] // ERROR `inline` is ambiguous
+pub fn qux() {}
+```
+
+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
+    * TODO example? This ones harder to do concisely afaik
+
+Helper attributes may not be used before the macro that introduces them.
+
+* What happens if two macros introduce the same helper, will the second one not
+  be able to see the attribute of the first anymore, assuming their order is
+  "firstmacro" "helper" "secondmacro"?
+
+> [!NOTE]
+> rustc currently allows derive helpers to be used before their attribute macro
+> introduces them into scope so long as they do not shadow any other attributes
+> or derive helpers that are otherwise correctly in scope. This behavior
+> deprecated and slated for removal.
+> <!-- ignore: requires external crates -->
+> ```rust,ignore
+> #[helper] // deprecated, hard error in the future
+> #[derive(WithHelperAttr)]
+> struct Struct {
+>     field: (),
+> }
+> ```
+>
+> For more details, see [Rust issue #79202](https://github.com/rust-lang/rust/issues/79202).
+
 r[names.resolution.expansion.macros]
 
 * .visitation-order