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

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

We were puzzling over this sentence and were wondering if you could clarify something.

(The phrase "the invocation of name" seemed out of place here, and we are assuming this should be "the name", since there isn't an invocation here.)

This ambiguities section starts off talking about an ambiguity involving macro invocations and expanded macros. But then this sentence seems to say, "oh and the ambiguity applies to imports, too.". Am I understanding it correctly that the rule here applies to macro invocations and imports? Is there a reason the start of the rule leaves out the "and imports" part?

[yaahc]

The "invocation" language came up because of this function and how it refers to the site the name being resolved came from as an invocation regardless of whether it was an import or a macro. I wasn't really sure if this was the more proper term or not, elsewhere in the reference I've used language like "name is used" to the same effect.

I just reread the beginning of this ambiguity section and at least the way I read and meant it it's not talking about this as only applying to macros. Whether or not the invocation is a macro or a use decl there have to be macro expansions involved in order for this lint to trigger. I did my best to make the language generic in the beginning and talk about candidates without specifically saying imports or macro definitions as the sources of those candidate bindings.

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

[traviscross]

Thanks @yaahc. Great work here, and great working with you on it. Thanks to @petrochenkov for the critical support.