Open
Description
The reference currently doesn't really make it clear how certain steps of translation happen, how they relate to one another, and the significance. I think it would be useful to have a section that makes this clear. Some rough thoughts on this:
- Better explain the process of tokenization, parsing, and tie this into crates as the unit of translation.
- Parsing's relationship with expansion, and maybe name resolution.
- Attribute behavior, such as inert/active, particularly when
cfgpruning is done. (specify how#![cfg(...)]works differently in the crate root versus anywhere else #103, Fix/clarify inert/active attributes, and attribute sequence. #565, Document behavior of #[cfg] in macros #836) - Attribute evaluation order (Is proc-macro-attribute application order defined? #692, Is the order of proc-macro expansion defined? #578), or maybe just a link to a dedicated chapter on expansion?
- Validation is performed after parsing/expansion.
- There have been some discussions of defining the language in terms of translations between different representations (tokens > AST > HIR > MIR > etc.), since some topics may be easier to document in those restricted definitions. I'm not sure how this relates, exactly, but seems relevant.
I am roughly thinking of something like https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/lexical-structure, or C++'s phases of translation.
This I think would also tie in with the rework of the lexical chapter (#567).