document where various bits of rust are desugared

[nikomatsakis]

It's been mentioned to me that it would be useful to have a list of all the "desugarings" that occur during the compilation process. In particular, which bits of Rust disappear during e.g. HIR conversion, HAIR conversion, MIR conversion. Here are some notes, I'd love to see someone turn some of this into a more detailed writeup! If you're interested, ping me here or (better) on gitter/IRC.

Desugaring that occur during HIR lowering

While constructing the HIR, we perform the following desugarings. It seems worth documenting these at a high-level (e.g, showing the equivalent Rust code), as well as covering some of the mechanisms we use to do it (e.g., the special spans we construct).

• the ? operator and catch blocks
  • desugared during HIR lowering, as explained here
• the for loop
  • desugared during HIR lowering
• the if let and while let forms
  • desugared during HIR lowering (if let, while let

Desugaring that occur during MIR lowering

While lowering to MIR, we perform the following desugarings:

• match expressions
  • patterns are desugared during HAIR construction into simpler form
    • this for example introduces explicit & patterns to implement default binding modes
  • then, desugared during MIR lowering
• calls
• control-flow into control-flow-graph

[balajisivaraman]

@nikomatsakis, I'd be interested in picking this up. I'll go through the current guide, and then get started with adding this, if that's OK.

[ghost]

@nikomatsakis I was planning to document with 3 points for every construct that is desugared

• which expression are they desugared to and what are their contents e.g. if let to match
• equivalent rust code - what would be nice to do here, document the corresponding desugared Rust code?or do we want to actually highlight the hir code inside rustc which does this?
• special mechanisms, unfortunately I have never contributed to rustc so I am actually using this to get into rust, could you please give pointers to special mechanisms I could research?

[mark-i-m]

Ping @balajisivaraman Any updates?

Also ping @nikomatsakis, I don't really have the knowledge to help anyone on this issue.

[balajisivaraman]

@mark-i-m, Unfortunately no, sorry. I'm still in the early stages of going through the current Rustc Guide, while working on a small fix to the compiler itself. It's going to be some time before I'm capable enough of actually making this change. If we have a deadline on this, someone else can pick it up.

Apologies again!

[mark-i-m]

@balajisivaraman No worries :)

[jieyouxu]

Triage: AFAIK HAIR isn't a thing now and it's probably more like THIR plus some build-phase MIR? But still good to describe what constructs gets desuguared between the various IRs.