Expand name resolution stub #2055

yaahc · 2025-10-20T20:40:30Z

currently mostly a skeleton of a draft so we can collaboratively massage it into shape more easily before filling in with proper reference verbiage.

hoping to take a significant chunk out of #568

traviscross · 2025-10-20T20:58:36Z

Thanks for posting. Lot of good here. The main thing I'd suggest, by way of helping to sharpen this up, would be to try to write a concise example after each claim, in as many cases as that might make sense, that demonstrates that the claim is true (and would not pass if the claim were false). Aside from the intrinsic benefit of having such examples, I think this might help to focus the text on the language-level effects. (It's not surprising, given the good research you've been doing, that some bits of this currently have some "description of the implementation" flavor.)

yaahc

a fair number of comments are also contained inline in the documents

src/names/name-resolution.md

src/items/use-declarations.md

yaahc · 2025-10-20T22:48:15Z

src/items/use-declarations.md


+* except where shadowing is allowed
+r[names.resolution.early.imports.errors.ambiguity.globvsglob]
+* it is an error to name an item through ambiguous use declarations


documented already

yaahc · 2025-10-20T22:48:43Z

src/items/use-declarations.md

+* 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


yaahc · 2025-10-20T23:13:10Z

src/names/namespaces.md

 For example, the [`cfg` attribute] and the [`cfg` macro] are two different entities with the same name in the macro namespace, but they can still be used in their respective context.

 r[names.namespaces.sub-namespaces.use-shadow]
 It is still an error for a [`use` import] to shadow another macro, regardless of their sub-namespaces.


I feel conflicted about this piece of info being in this section. On the one hand sub-namespaces are quite similar to shadowing, though they work via an independent mechanism. On the other, I'm fairly certain this is exclusively referring to the TextualVsPathBased ambiguity error with the added bit of information of pointing out that this is unaffected by sub-namespaces. I need to verify this but I suspect this is because of how imports bring in names from all namespaces so it probably always counts as a sub-namespace match preventing the subnamespace mismatch early exit from ever bailing before we report the ambiguity error.

Assuming this explanation is correct, we can maybe find a place within the use-declarations or mbe chapters to mention how imports are unaffected by subnamespaces. I'm currently wondering if it would make sense to move the subnamespace stuff to live in one of the macros chapters and link to it from here.

src/items/use-declarations.md

petrochenkov · 2025-10-21T10:50:49Z

src/items/use-declarations.md

+    * [macro.decl.scope.path.ambiguity]
+r[names.resolution.early.imports.errors.ambiguity.globvsouter]
+* it is an error to shadow an outer name binding with a glob import
+    * This seems to only apply to early resolution (duh, I documented this as part of an early resolution codepath)


Most of the new text here need to be moved to name resolution, IMO.

I'd use src/items/use-declarations.md for things that happen at import definition time.
But most of ambiguity errors here do not happen at import definition time, but rather when someone tries to resolve a name from some unlucky point of view.

Only some situations create inherently ambiguous import definitions, like glob-vs-glob conflicts, and even then they are not reported at definition time.

I don't mind moving this but the reason I put them alongside their items was because that seemed most consistent with how we documented other parts of name resolution, specifically how the names that are introduced by each item are documented next to their items and then theres an aggregated list linking to all those sections in the namespaces chapter.

My plan was to put ambiguity and shadowing sections alongside their items and aggregate links to all those sections in name-resolution.md.

You can see where I discussed this plan with eric starting here: #t-lang-docs/reference > name resolution @ 💬

I've gone ahead and moved the ambiguity sections to the name-res chapter.

src/names/name-resolution.md

petrochenkov · 2025-10-21T10:56:19Z

src/names/name-resolution.md

+
+r[names.resolution.early.imports.shadowing]
+
+The following is a list of situations where shadowing of use declarations is permitted:


Suggested change

The following is a list of situations where shadowing of use declarations is permitted:

The following is a list of situations where shadowing of use declarations is not permitted:

?

I think the original text is correct.

Use glob shadowing: https://doc.rust-lang.org/nightly/reference/items/use-declarations.html#r-items.use.glob.shadowing
macro textual scope shadowing: https://doc.rust-lang.org/nightly/reference/macros-by-example.html#r-macro.decl.scope.textual.shadow

In my mind the "not permitted" set is the list of ambiguity errors below

petrochenkov · 2025-10-21T10:56:54Z

src/names/name-resolution.md

+* .visitation-order
+    * derive helpers
+        * not visited when resolving derive macros in the parent scope (starting scope)
+    * derive helpers compat


Same concern as above about this being deprecated and removed next year.

traviscross · 2025-10-22T01:18:48Z

@ehuss and I are looking at this together on the lang-docs office hours call, and we just wanted to express our appreciation to @petrochenkov for having been so responsive with @yaahc on working out the details here. This is a chapter that we've long wanted to exist, and we're thrilled and appreciative that @yaahc is digging in to shape this up.

src/macros-by-example.md

yaahc · 2025-11-07T22:50:51Z

src/names/name-resolution.md

+pub fn qux() {}
+```
+
+r[names.resolution.early.imports.errors.ambiguity.derivehelper]


TODO: go back and add a section mentioning the proc macro-related ambiguity errors to the proc macros chapter and link to the name-res chapter

src/macros-by-example.md

yaahc · 2025-11-11T19:54:12Z

src/names/name-resolution.md

+[visibility]: ../visibility-and-privacy.md
+[permitted]: name-resolution.md#r-names.resolution.expansion.imports.shadowing
+[macro invocations]: ../macros.html#macro-invocation
+[path-based scope]: ../macros-by-example.html#r-macro.decl.scope.path-based


This currently links to the macros-by-example chapter, but in actuality, this applies to all the various forms of proc macros as well. I'd like a better top level section to link to that covers both kinds of macros

yaahc · 2025-11-19T21:58:49Z

src/names/name-resolution.md

+The expansion process is iterative, alternately resolving imports, resolving
+and expanding macro invocations, then repeating until there are no further
+macros invocations to resolve. Once this process is completed all the imports
+are resolved again to ensure that the macro expansion process did not introduce
+any new ambiguious imports.


do we want to talk about this? feels like an implementation detail but
also really helps to understand certain kinds of ambiguity errors that users
can run into.

If you want to consider an alternate approach, it may be possible to not include this paragraph and don't focus on the "iterative" nature. The chapter could instead focus on what must be true or what the end result is. So it could have separate rules that say things like:

After expansion-time name resolution, the AST must not contain any unexpanded macro invocations.

Every (...) resolves to a valid definition that exists in the final AST (or an external crate).

The resolution of imports must be stable. After expansion, imports in the fully expanded AST must resolve to the same definition...

?Maybe say something about order-dependency?

etc.

yaahc · 2025-11-19T22:05:16Z

src/names/name-resolution.md

+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)

yaahc · 2025-11-19T22:06:23Z

src/names/name-resolution.md

+* 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"?

yaahc · 2025-11-19T22:08:49Z

src/procedural-macros.md

 [type expressions]: types.md#type-expressions
 [type]: types.md
 [union]: items/unions.md
+[name resolution ambiguities]: ../names/name-resolution.html#r-names.resolution.expansion.imports.errors.ambiguity


more precise link

chorman0773 · 2025-11-20T20:15:45Z

src/names/name-resolution.md

+        * not visited in 2018 and later when `#[no_implicit_prelude]` is present
+    * stdlibprelude
+        * always visited for macro resolutions
+        * is it? what about no-std + no-core?


no_core isn't a user visible attribute, it's an implementation detail of core, and perma-unstable as far as I'm aware.

yaahc · 2025-11-20T22:03:30Z

src/names/namespaces.md


 r[names.namespaces.sub-namespaces.use-shadow]
 It is still an error for a [`use` import] to shadow another macro, regardless of their sub-namespaces.
+* TODO revisit


Revisiting this. I think I've decided against wanting to move the entire sub-namespaces section into the name resolution chapter. I was consider if it made sense to argue that they aren't a true namespace since the mechanism through which they're implemented is different and that they're actually a property of the name resolution algorithm that creates "apparent sub-namespaces" or something along those line. I ended up convincing myself that this is a distinction without a difference and its just simpler pedagogically to call them sub-namespaces.

I do think I want to give the use-shadowing subsection the same treatment as the other ambiguity errors, remove the section here and add an admonition linking to the relevant section in name-resolution.

yaahc · 2025-11-20T22:14:54Z

src/names/name-resolution.md

+```
+
+r[names.resolution.early.imports.ambiguity.pathvstextualmacro]
+Path-based scope bindings for macros may not shadow textual scope bindings to macros. For bindings from [use declarations], this applies regardless of their [sub-namespace].


implication here that I need to investigate: that it is possible to have path-based bindings to macros that would shadow textual bindings if imported but not if otherwise defined in the same scope.

yaahc · 2025-11-20T22:18:33Z

src/names/name-resolution.md

+Macros are resolved by iterating through the available scopes until a candidate
+is found. Macros are split into two sub-namespaces, one for bang macros, and
+the other for attributes and derives. Resolution candidates from the incorrect
+sub-namespace are ignored. The available scopes are visited in the following order.


I'm not at all happy with this, in particular the first sentence seems like a gross oversimplification. I wrote this as is because I was trying to find some way to introduce the scope visitation order logic.

yaahc force-pushed the name-res branch from 2e2c9fd to 154c958 Compare October 20, 2025 20:51

yaahc force-pushed the name-res branch from 154c958 to 84283b1 Compare October 20, 2025 21:09

yaahc commented Oct 20, 2025

View reviewed changes

src/names/name-resolution.md Show resolved Hide resolved

src/names/name-resolution.md Outdated Show resolved Hide resolved

src/names/name-resolution.md Outdated Show resolved Hide resolved

src/names/name-resolution.md Outdated Show resolved Hide resolved

yaahc force-pushed the name-res branch from 84283b1 to dfee04f Compare October 20, 2025 22:21

yaahc commented Oct 20, 2025

View reviewed changes

yaahc force-pushed the name-res branch from dfee04f to 4af8acb Compare October 20, 2025 22:49

yaahc commented Oct 20, 2025

View reviewed changes

petrochenkov reviewed Oct 21, 2025

View reviewed changes

yaahc mentioned this pull request Oct 21, 2025

Early Name Resolution: Imports rust-lang/project-goal-reference-expansion#8

Open

This comment has been minimized.

Sign in to view

rustbot added the S-waiting-on-author Status: The marked PR is awaiting some action (such as code changes) from the PR author. label Oct 21, 2025

yaahc force-pushed the name-res branch 6 times, most recently from 5397d08 to 1bd3afe Compare October 29, 2025 21:29

yaahc force-pushed the name-res branch 9 times, most recently from 80fd707 to 570bedd Compare November 7, 2025 22:43

yaahc commented Nov 7, 2025

View reviewed changes

src/macros-by-example.md Show resolved Hide resolved

yaahc commented Nov 7, 2025

View reviewed changes

src/macros-by-example.md Outdated Show resolved Hide resolved

yaahc mentioned this pull request Nov 7, 2025

Document name resolution rust-lang/project-goal-reference-expansion#17

Open

Amanieu mentioned this pull request Nov 11, 2025

Stabilize the supertrait_item_shadowing feature rust-lang/rust#148605

Open

yaahc force-pushed the name-res branch from 570bedd to a8b8581 Compare November 11, 2025 19:51

yaahc commented Nov 11, 2025

View reviewed changes

yaahc force-pushed the name-res branch from cb67cdf to 584d297 Compare November 19, 2025 22:07

yaahc commented Nov 19, 2025

View reviewed changes

yaahc force-pushed the name-res branch 2 times, most recently from 7e17934 to 4744e19 Compare November 20, 2025 19:47

chorman0773 reviewed Nov 20, 2025

View reviewed changes

yaahc force-pushed the name-res branch from 4744e19 to d4eb51d Compare November 20, 2025 21:40

Expand name resolution stub

3d7f6c5

yaahc force-pushed the name-res branch 3 times, most recently from 9ada73e to f982337 Compare November 20, 2025 21:48

yaahc commented Nov 20, 2025

View reviewed changes

yaahc force-pushed the name-res branch from f982337 to 73a1f2a Compare November 20, 2025 22:12

yaahc commented Nov 20, 2025

View reviewed changes

yaahc force-pushed the name-res branch from 73a1f2a to eb7cc1e Compare November 20, 2025 22:20

yaahc marked this pull request as ready for review November 20, 2025 22:22

rustbot added the S-waiting-on-review Status: The marked PR is awaiting review from a maintainer label Nov 20, 2025

rewrite bullet points as prose

64c29bd

yaahc force-pushed the name-res branch from eb7cc1e to 64c29bd Compare November 20, 2025 22:29


		r[names.resolution.early.imports.shadowing]

		The following is a list of situations where shadowing of use declarations is permitted:

		It is an error to use a user defined attribute or derive macro with the same
		name as a builtin attribute (e.g. inline)

Expand name resolution stub #2055

Are you sure you want to change the base?

Expand name resolution stub #2055

Conversation

yaahc commented Oct 20, 2025

Uh oh!

traviscross commented Oct 20, 2025

Uh oh!

yaahc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yaahc Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

traviscross commented Oct 22, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

yaahc Oct 21, 2025 •

edited

Loading