Document name resolution.

[ehuss]

Name resolution should be documented. This is a large topic. A few pieces I can think of:

• How items are added to scope (Items must show what paths they make available. #129).
  • Don't forget tricky things like macro_use and macro_export.
• The different namespaces (type, value, and macro?). DONE Start documenting name resolution. #937
• Should ribs be explained? Seems like a useful way to talk about a scope region.
• What is a valid path?
  • And document how things like generic args work in paths. See Possibly incorrect syntax Enum::<Type, Params>::Variant allowed since 1.33 rust#69356 for an unusual example.
• The different scope layers. (See visit_scopes). It should be clear how shadowing works. I saw this list once, which is likely incorrect, but a starting point:
  • local variables
  • items in unnamed blocks
  • items in the current module
  • crate names in the "extern prelude"
  • standard library prelude
  • language prelude (built-in types)
• I think all prelude kinds should be documented and explicitly named. Currently the reference mentions "the prelude" which is ambiguous, and the extern prelude. There are other preludes like the language prelude, the macro_use prelude, the "tool prelude" (I think), etc. DONE Start documenting name resolution. #937
  • no_implicit_prelude should clarify which preludes are not included. DONE Start documenting name resolution. #937
  • crates-and-source-files.md#preludes-and-no_std should also be updated. DONE Start documenting name resolution. #937
  • modules.md#prelude-items doesn't mention extern crate prelude. It needs updating. DONE Start documenting name resolution. #937
• I believe there are some complexities around name resolution during import, particularly with macros, since the modules are in flux.
• How does resolution work that a struct field and method can have the same name? I believe https://github.com/rust-lang/reference/blob/master/src/expressions/field-expr.md covers this sufficiently.
• There are a lot of details that will be difficult to cover. For example: Ambiguity errors in 2018 uniform import paths are not technically necessary rust#56414.
• See also: https://github.com/rust-lang/rfcs/blob/master/text/1560-name-resolution.md
• Items declared inside functions cannot refer to the type parameters of the enclosing function.
• Interesting insight on how macro resolution works: https://internals.rust-lang.org/t/announcing-rust-2018-beta-release/8901/17
• Detailed comment from petrochenkov about item containers: Use Declarations in More Places rfcs#1976 (comment)
• This simplifying pr would be good to understand: resolve: Simplify import resolution for mixed 2015/2018 edition mode rust#58349
• Interesting comment: resolve: Account for new importable entities rust#59047 (comment)
• This PR has some interesting insight into macro paths: resolve: Implement prelude search for macro paths, implement tool attributes rust#52841
• How does use handle something that is available in multiple namespaces (such as a module and a type).
• Restricted shadowing: resolve: Relax shadowing restrictions on macro-expanded macros rust#53778 (comment)
• Cover type-relative resolution described in Document type_alias_enum_variants #631 (comment).

[gnzlbg]

cc @petrochenkov

[ehuss]

Just to kick off a little discussion of the outline: a long while back I started an outline here: ehuss@bb2e84b

• Name resolution
  • Namespaces
  • Scopes
  • Definitions
    • Preludes
  • Paths
  • Module and macro resolution

Since I think this will overall be a meaty topic, I think it would be good to split it into separate files from the start.

I think the "Paths" chapter should be moved underneath name resolution, since it doesn't really belong in the lexical chapter.

Some high-level questions:

• Does it make sense to split it up like this?
• I was thinking the "Definitions" chapter would list all the things that can introduce an identifier into scope. However, an alternative would be to spread that information out across the entire reference. So, for example, the struct item chapter could specify how various identifiers in a struct definition introduce different things into different namespaces. One concern is that could introduce a lot of verbiage across the entire reference. However, it would probably make more sense to describe that in-place instead of consolidating it in one chapter. So "Definitions" could possibly be removed, or maybe just shrunk into a small subsection in the chapter introduction.
• What to call the things that identifiers can refer to? I was using "elements", but I don't think there is any precedent for that. It would be nice to have a word to refer to items+types+bindings+macros+attributes+whatever, but I couldn't find one already in use.

[petrochenkov]

I was thinking the "Definitions" chapter would list all the things that can introduce an identifier into scope.

I think it would be good to have at least a list of definitions with links to other chapters, even if majority of the text will be elsewhere.

What to call the things that identifiers can refer to?

They are called NameBinding in the compiler, but it's a very old and sufficiently inconsistent name.
"Name introduction" perhaps? The introduction may either be a "name definition", or an "import"/"reexport" referring to a different name introduction.

[Havvy]

Just to add a couple more questions:

1. Do we want to call them "names" or "bindings"?
2. Can we pick a better term than "name resolution"? I know it's the name we use in the compiler, but "resolve" doesn't really mean anything on its own? You could argue these names are references and we dereference them, but we already use Deref for pointers.

---

I like the term introduction for the places a binding/name is introduced. Also +1 on having a central list that links to more descriptions in the specific chapters.

For "elements", we could just be informal and say "parts of a program".

[petrochenkov]

Can we pick a better term than "name resolution"?

In C++ it's officially called "name lookup", for example.

Do we want to call them "names" or "bindings"?

I would personally prefer "names".
AFAIK, the term "bindings" is only used for local variables in the user-facing documentation, and all those "variable vs binding" explanations never made sense to me.

[Havvy]

AFAIK, the term "bindings" is only used for local variables in the user-facing documentation,

Yes. That is entirely correct and I am way too tired.