document where various bits of rust are desugared

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

Start with the linked HIR lowering.rs locations, the HAIR pattern code in src/librustc_mir/hair/pattern/mod.rs, and the MIR matches directory. Trace the listed HIR, HAIR, and MIR transformations, then expand the checklist into a high-level writeup with equivalent Rust examples and the relevant mechanisms; done means the documented desugarings cover the listed cases and compilation stages.