Open
Description
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
andmacro_export
.
- Don't forget tricky things like
- 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.
- And document how things like generic args work in paths. See Possibly incorrect syntax
- 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).