Document name resolution.

Start by reviewing the unchecked topics in the issue and the Rust Reference sections linked from it, especially visit_scopes in compiler/rustc_resolve/src/lib.rs. Use the linked RFCs and related issues for background on paths, scope layers, shadowing, imports, macros, and type-relative resolution. Done means the remaining name-resolution behavior is documented clearly in the appropriate Reference pages.

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

• How items are added to scope (#129).
  • Don't forget tricky things like macro_use and macro_export.
• The different namespaces (type, value, and macro?). DONE #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 https://github.com/rust-lang/rust/issues/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 #937
  • no_implicit_prelude should clarify which preludes are not included. DONE #937
  • crates-and-source-files.md#preludes-and-no_std should also be updated. DONE #937
  • modules.md#prelude-items doesn't mention extern crate prelude. It needs updating. DONE #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: https://github.com/rust-lang/rust/issues/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: https://github.com/rust-lang/rfcs/pull/1976#issuecomment-301903528
• This simplifying pr would be good to understand: https://github.com/rust-lang/rust/pull/58349
• Interesting comment: https://github.com/rust-lang/rust/pull/59047#discussion_r264027037
• This PR has some interesting insight into macro paths: https://github.com/rust-lang/rust/pull/52841
• How does use handle something that is available in multiple namespaces (such as a module and a type). https://github.com/rust-lang/reference/pull/1052
• Restricted shadowing: https://github.com/rust-lang/rust/pull/53778#issuecomment-419224049
• Cover type-relative resolution described in https://github.com/rust-lang/reference/issues/631#issuecomment-508809177.