Document the order preludes are resolved

src/names/preludes.md

@@ -142,6 +142,34 @@ r[names.preludes.tool.intro]
 The tool prelude includes tool names for external tools in the [type
 namespace]. See the [tool attributes] section for more details.
 
+r[names.preludes.precedence]
+## Prelude precedence
+Names of items are resolved in the following order:
+
+Value namespace: only the standard library prelude contains items in this namespace.
+
+1. Explicit definitions (including imports)
+2. Standard library prelude
+
+Type namespace:
+
+1. Explicit definitions (including imports)
+2. Extern prelude
+3. Tool prelude
+4. Standard library prelude
+5. Language prelude
+
+Macro namespace:
+
+1. Explicit definitions (including imports)
+    1. [Derive helpers]
+    2. [Macros by example][macro_rules]
+2. Macro prelude
+3. Standard library prelude
+4. [Language prelude][Built-in attributes]
+
+Currently, the ordering between library and language is not observable because there are no items in both namespaces.
+
 r[names.preludes.no_implicit_prelude]
 ## The `no_implicit_prelude` attribute
 
@@ -161,6 +189,8 @@ r[names.preludes.no_implicit_prelude.edition2018]
 > Starting in the 2018 edition, it will remove the `macro_use` prelude.
 
 [`extern crate`]: ../items/extern-crates.md
+[macro_rules]: ../macros-by-example.md
+[Derive helpers]: ../names/scopes.html#derive-macro-helper-attributes
 [`macro_use` attribute]: ../macros-by-example.md#the-macro_use-attribute
 [`macro_use` prelude]: #macro_use-prelude
 [`no_std` attribute]: #the-no_std-attribute

src/procedural-macros.md

@@ -94,7 +94,7 @@ These macros are defined by a [public] [function] with the `proc_macro`
 output [`TokenStream`] replaces the entire macro invocation.
 
 r[macro.proc.function.namespace]
-The `proc_macro` attribute defines the macro in the [macro namespace] in the root of the crate.
+The `proc_macro` attribute defines the macro in the [bang-style sub-namespace][sub-namespace] of 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.
@@ -144,7 +144,7 @@ Custom derive macros are defined by a [public] [function] with the
 `proc_macro_derive` attribute and a signature of `(TokenStream) -> TokenStream`.
 
 r[macro.proc.derive.namespace]
-The `proc_macro_derive` attribute defines the custom derive in the [macro namespace] in the root of the crate.
+The `proc_macro_derive` attribute defines the custom derive in the [attribute sub-namespace][sub-namespace] of the [macro namespace] in the root of the crate.
 
 r[macro.proc.derive.output]
 The input [`TokenStream`] is the token stream of the item that has the `derive`
@@ -240,7 +240,7 @@ including other [attributes] on the [item]. The returned [`TokenStream`]
 replaces the [item] with an arbitrary number of [items].
 
 r[macro.proc.attribute.namespace]
-The `proc_macro_attribute` attribute defines the attribute in the [macro namespace] in the root of the crate.
+The `proc_macro_attribute` attribute defines the attribute in the [attribute sub-namespace][sub-namespace] of 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.
@@ -399,6 +399,7 @@ their equivalent `#[doc = r"str"]` attributes when passed to macros.
 [item]: items.md
 [items]: items.md
 [macro namespace]: names/namespaces.md
+[sub-namespace]: names/namespaces.md#sub-namespaces
 [module]: items/modules.md
 [patterns]: patterns.md
 [public]: visibility-and-privacy.md