rust-lang / rust-lang/reference
Consider describing the phases of translation
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 1.6k
- Forks
- 607
- PR merge metrics
- PR metrics pending
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. (#103, #565, #836) - Attribute evaluation order (#692, #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).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Rust Reference's lexical chapter and the linked crates-and-source-files section, then review the related issues on attributes, expansion, and lexical rework. Done means the Reference clearly describes translation phases, their relationships, and the significance of tokenization, parsing, expansion, validation, and intermediate representations.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100