Document the order preludes are resolved

[jyn514]

Also document the derive macro sub-namespace; apparently it was missing before.

cc rust-lang/rust#66079 (comment), rust-lang/rust#138840

[petrochenkov]

This doesn't look correct, language prelude should be considered last.

In the compiler the order can be found in fn visit_scopes (it also describes the motivation behind the scope ordering).

• Type namespace: module items ("explicit definitions") -> extern prelude -> tool prelude -> stdlib prelude -> language prelude (built-in types).
• Value namespace: module items -> stdlib prelude.
• Macro namespace: derive helpers -> legacy derive helpers -> macro_rules -> module items -> macro_use prelude -> stdlib prelude -> language prelude (built-in attributes).

Language and macro prelude. If an item is present in both preludes, an error is emitted.

Built-in attributes conflict with all other scopes (in attr sub-namespace), not just with preludes.

[petrochenkov]

(This is not relevant to preludes, but the "macro_rules -> module items" should ideally be intermixed, but it's under-implemented and stubbed by errors, so probably no need to specify it for now.)

[jyn514]

ok; clearly my testing was wrong and i need to think about exactly why. i have fixed the first commit (about sub-namespaces) in the meantime.

[jyn514]

actually i have a question for you: visit_scopes says that in the type namespace, the extern prelude takes precedence over tool modules. this makes sense by the reasoning there since tool modules are closed but the extern prelude is not (i guess in source this correponds to the fact that extern crate can be anywhere but register_tool can only be at the crate root). but for tools it's not ideal because it means that extern crate rustfmt; will break rustfmt::skip.

that doesn't matter so much today because the tool namespace is controlled. but if we want to stabilize register tool, it becomes more of a problem. if the precedence went the other way, with tools resolved before the extern prelude, there would be a workaround: use ::rustfmt to refer to the crate. but there is no such workaround to refer to the tool module.

[jyn514]

oh lol i didn't ask a question. my question is: do you agree that's a problem? and if so, do you have a preferred solution?

my preferred solution is to have tool modules take precedence over the extern prelude, but i'm curious to hear your thoughts.