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.

[ehuss]

Something I'm missing is a discussion about blocks, and how they can introduce essentially an anonymous module (ModuleKind::Block). That's important when trying to understand the module tree and how some resolutions and ambiguities resolve differently. I was looking at this example:

mod bar {
    pub struct Name;
}

mod baz {
    pub struct Name;
}

use baz::Name;

pub fn foo() {
    use bar::*;
    Name; // resolves to bar::Name
}

I think the reason it resolves to bar::Name is because it is nested inside an anonymous module. If we were to rewrite this to:

mod bar {
    pub struct Name;
}

mod baz {
    pub struct Name;
}

use baz::Name;
use bar::*;

pub fn foo() {
    Name; // resolves to baz::Name
}

If we were to ignore blocks, and pretend they don't exist from a module-hierarchy perspective, I would expect both these examples to be the same. I'm not sure if I'm understanding this correctly, since resolution within a block still "sees" everything outside of the block (inside it's module).

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