rewrite bullet points as prose

Co-authored-by: Vadim Petrochenkov <[email protected]>

Update src/macros-by-example.md

Co-authored-by: Eric Huss <[email protected]>
Update src/names/name-resolution.md

Co-authored-by: Tshepang Mbambo <[email protected]>
Update src/names/name-resolution.md

Co-authored-by: Eric Huss <[email protected]>
Apply suggestions from code review

Co-authored-by: Eric Huss <[email protected]>
Update src/names/name-resolution.md

Co-authored-by: Eric Huss <[email protected]>
Update src/names/name-resolution.md

Co-authored-by: Eric Huss <[email protected]>
Update src/names/name-resolution.md

Co-authored-by: Eric Huss <[email protected]>
split expansion intro into multiple sections

add backticks around use for `use` declarations

Author: yaahc

src/items/use-declarations.md

@@ -116,7 +116,7 @@ They may create bindings for:
 * [Built-in types]
 * [Attributes]
 * [Derive macros]
-* [Macros by example]
+* [`macro_rules`]
 
 r[items.use.path.disallowed]
 They cannot import [associated items], [generic parameters], [local variables], paths with [`Self`], or [tool attributes]. More restrictions are described below.
@@ -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,22 +394,19 @@ 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
-[associated items]: associated-items.md
 [Attributes]: ../attributes.md
 [Built-in types]: ../types.md
 [Derive macros]: macro.proc.derive
 [Enum variants]: enumerations.md
+[`extern crate`]: extern-crates.md
+[`macro_rules`]: ../macros-by-example.md
+[`self`]: ../paths.md#self
+[associated items]: associated-items.md
 [extern prelude]: ../names/preludes.md#extern-prelude
 [generic parameters]: generics.md
 [items]: ../items.md
 [local variables]: ../variables.md
+[name resolution ambiguities]: names.resolution.expansion.imports.ambiguity
 [namespace]: ../names/namespaces.md
 [namespaces]: ../names/namespaces.md
 [paths]: ../paths.md

src/macros-by-example.md

@@ -326,20 +326,22 @@ fn foo() {
 // m!(); // Error: m is not in scope.
 ```
 
-* textual scope name bindings for macros may shadow path-based scope bindings
-  to macros
+r[macro.decl.scope.textual.shadow.path-based]
+Textual scope name bindings for macros shadow path-based scope bindings to macros.
 
 ```rust
-macro_rules! m {
+#[macro_export]
+macro_rules! m2 {
     () => {
-        println!("m");
+        println!("m2");
     };
 }
 
-#[macro_export]
-macro_rules! m2 {
+m!(); // prints "m2\n"
+
+macro_rules! m {
     () => {
-        println!("m2");
+        println!("m");
     };
 }
 
@@ -348,6 +350,53 @@ use crate::m2 as m;
 m!(); // prints "m\n"
 ```
 
+> [!NOTE]
+>
+> For areas where shadowing is not allowed, see [name resolution ambiguities].
+
+r[macro.decl.scope.path-based]
+### Path-based scope
+
+r[macro.decl.scope.path-based.intro]
+By default, a macro has no path-based scope. Macros can gain path-based scope in two ways:
+
+* [Use declaration re-export]
+* [`macro_export`]
+
+r[macro.decl.scope.path.reexport]
+Macros can be re-exported to give them path-based scope from a module other than the crate root.
+
+```rust
+mac::m!(); // OK: Path-based lookup finds m in the mac module.
+
+mod mac {
+    macro_rules! m {
+        () => {};
+    }
+    pub(crate) use m;
+}
+```
+
+r[macro.decl.scope.path-based.visibility]
+Macros have an implicit visibility of `pub(crate)`. `#[macro_export]` changes the implicit visibility to `pub`.
+
+```rust,compile_fail,E0364
+macro_rules! private_m {
+    () => {};
+}
+
+#[macro_export]
+macro_rules! pub_m {
+    () => {};
+}
+
+pub(crate) use private_m as private_macro; // OK
+pub use pub_m as pub_macro; // OK
+
+pub use private_m; // ERROR: `private_m` is only public within
+                   // the crate and cannot be re-exported outside
+```
+
 <!-- template:attributes -->
 r[macro.decl.scope.macro_use]
 ### The `macro_use` attribute
@@ -502,25 +551,6 @@ By default, macros only have [textual scope][macro.decl.scope.textual] and canno
 > # fn main() {}
 > ```
 
-r[macro.decl.scope.path.reexport]
-
-* macros can be re-exported to give them path-based scope from a module other than the crate root.
-    * there's some visibility stuff here that may already be mentioned
-      elsewhere. I'm pretty sure that w/o a #[macro_export] the macro being
-      re-exported is implicitly pub(crate) and with one it is implicitly pub.
-      The later is mentioned below, don't remember where I saw the former.
-
-```
-mac::m!(); // OK: Path-based lookup finds m in the mac module.
-
-mod mac {
-    macro_rules! m {
-        () => {};
-    }
-    pub(crate) use m;
-}
-```
-
 r[macro.decl.scope.macro_export.export]
 The `macro_export` attribute causes a macro to be exported from the crate root so that it can be referred to in other crates by path.
 
@@ -754,14 +784,17 @@ expansions, taking separators into account. This means:
 
 For more detail, see the [formal specification].
 
+[Hygiene]: #hygiene
+[Metavariables]: #metavariables
+[Repetitions]: #repetitions
+[Use declaration re-export]: items/use-declarations.md#use-visibility
+[`macro_export`]: #the-macro_export-attribute
+[`$crate`]: macro.decl.hygiene.crate
 [`extern crate self`]: items.extern-crate.self
 [`macro_use` prelude]: names/preludes.md#macro_use-prelude
 [block labels]: expr.loop.block-labels
 [delimiters]: tokens.md#delimiters
 [formal specification]: macro-ambiguity.md
-[Hygiene]: #hygiene
 [loop labels]: expressions/loop-expr.md#loop-labels
-[Metavariables]: #metavariables
-[Repetitions]: #repetitions
+[name resolution ambiguities]: names/name-resolution.md#r-names.resolution.expansion.imports.ambiguity
 [token]: tokens.md
-[`$crate`]: macro.decl.hygiene.crate

src/macros.md

@@ -106,15 +106,25 @@ macro_rules! example {
 example!();
 ```
 
+r[macro.invocation.name-resolution]
+
+Macros invocations can be resolved via two kinds of scopes:
+
+* Textual Scope
+    * [Textual scope `macro_rules`](macros-by-example.md#r-macro.decl.scope.textual)
+* Path-based scope
+    * [Path-based scope `macro_rules`](macros-by-example.md#r-macro.decl.scope.path-based)
+    * [Procedural macros]
+
+[External blocks]: items/external-blocks.md
 [Macros by Example]: macros-by-example.md
 [Procedural Macros]: procedural-macros.md
+[`macro_rules`]: macros-by-example.md
 [associated items]: items/associated-items.md
 [delimiters]: tokens.md#delimiters
 [expressions]: expressions.md
 [items]: items.md
-[`macro_rules`]: macros-by-example.md
 [patterns]: patterns.md
 [statements]: statements.md
 [types]: types.md
 [visibility qualifiers]: visibility-and-privacy.md
-[External blocks]: items/external-blocks.md