Add section on expansion-time (early) name resolution

[yaahc]

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]

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

[petrochenkov]

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

[traviscross]

@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.

[traviscross]

Thanks to @yaahc for joining us on the lang-docs office hours today to speedrun many revisions to this chapter, which is really shaping up.

[rustbot]

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[yaahc]

I went to update this example because

• I realized that for the purposes of this ambiguity error, only path-based scope bindings from use declarations are relevant. The only other sources of path-based scope bindings are:
  • #[macro_export], which unconditionally adds an entry to the crate root, which by definition is always going to be in the outermost module scope and couldn't otherwise lexically shadow any textual macro bindings in a crate.
  • proc macros, which cannot be used in the crate they're defined, and must be imported via a use declaration in which case it's using an import, or (and I'm not sure this works) a macro_use attr on an extern crate statement for the proc macro crate, in which case the candidate would live in the macro_use prelude and this this ambiguity error would never apply (nor need to)
• I wanted to demonstrate the "regardless of their sub-namespace" claim as well as the core claim.

unfortunately, my attempt compiled without issue:

macro_rules! m {
    () => {};
}

pub fn foo() {
    m!();

    use myinline::inline as m;
}

I think the issue here is that I attempted to combine this lint with a rule in namespaces.md based on a misunderstanding of what that rule was talking about.

I believe this rule is meant to clarify the scope of https://doc.rust-lang.org/reference/items/use-declarations.html#r-items.use.restrictions.duplicate-name

[yaahc]

should this clarify that each of these bullets represent one or more scopes or is this intuitively obvious?

[traviscross]

Probably worth clarifying.