From 5167e1360120d92fda475485cf7fc79a03e00302 Mon Sep 17 00:00:00 2001 From: jyn Date: Sat, 22 Mar 2025 16:10:22 -0400 Subject: [PATCH 1/3] Document that derives go in the attribute sub-namespace --- src/procedural-macros.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/procedural-macros.md b/src/procedural-macros.md index 4627ffcfa..07f91b0d2 100644 --- a/src/procedural-macros.md +++ b/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 From f2f56b1e3469848de2d66786550795f3e1c6f043 Mon Sep 17 00:00:00 2001 From: jyn Date: Sat, 22 Mar 2025 16:10:33 -0400 Subject: [PATCH 2/3] Document the order preludes are resolved --- src/names/preludes.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/names/preludes.md b/src/names/preludes.md index 3764c1725..816adaeed 100644 --- a/src/names/preludes.md +++ b/src/names/preludes.md @@ -142,6 +142,16 @@ 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: + +1. Explicit definitions (including imports) +2. Language and macro prelude. If an item is present in both preludes, an error is emitted. +3. Extern prelude +4. Tool prelude +5. Standard library prelude + r[names.preludes.no_implicit_prelude] ## The `no_implicit_prelude` attribute From bed5d2983eac97ef804b3bb813fe79c72cd2c537 Mon Sep 17 00:00:00 2001 From: jyn Date: Sat, 29 Mar 2025 00:23:34 -0400 Subject: [PATCH 3/3] Document that prelude resolution happens in three different namespaces --- src/names/preludes.md | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/src/names/preludes.md b/src/names/preludes.md index 816adaeed..9103a5879 100644 --- a/src/names/preludes.md +++ b/src/names/preludes.md @@ -146,11 +146,29 @@ 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. Language and macro prelude. If an item is present in both preludes, an error is emitted. -3. Extern prelude -4. Tool prelude -5. Standard library prelude +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 @@ -171,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