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.

yaahc · 2025-11-07T22:49:57Z

src/macros-by-example.md

TODO: come back and add a section mentioning the macro-related ambiguity errors and linking to the name-res chapter

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

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

src/macros-by-example.md

 // m!(); // Error: m is not in scope.
 ```

+* textual scope name bindings for macros may shadow path-based scope bindings


should this get a rule?

Seems so, yes.

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 8 times, most recently from 22aaa92 to 80fd707 Compare November 7, 2025 22:39

yaahc added 2 commits November 7, 2025 14:42

Expand name resolution stub

6fc4e4e

rewrite bullet points as prose

570bedd

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

yaahc commented Nov 7, 2025

View reviewed changes

yaahc mentioned this pull request Nov 7, 2025

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

Open


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

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

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!

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!

5 participants

yaahc Oct 21, 2025 •

edited

Loading