Add a chapter on divergence

[jackh726]

It was little tricky when trying to describe diverging blocks. The compiler's implementation maintains sort of a "global state" when checking an expression and sub-expressions, which it resets on conditional things. Semantically, I think the way I worded it is much clearer than trying to match the implementation.

Happy to hear any specific feedback, Lcnr made did an initial review pass in rust-lang/project-goal-reference-expansion@4079171, so the second commit tries to address that.

[traviscross]

Thanks for the PR @jackh726; I can tell this was written carefully. It will be good to get more of this documented. In particular, it'll be good to have the fallback behavior documented.

I'll leave some notes inline. Probably we'll want to move some things around.

Adding more examples -- even beyond what I'll note specifically inline -- would be particularly good for this material. It's helpful when each rule has one or more concise and testable examples demonstrating exactly what the rule means to express.

[jackh726]

Thanks for the review @traviscross. Good points here, I'll work on sorting through them today/tomorrow.

Happy to jump on a call at some point too, if you think any of these could use further discussion.

[traviscross]

@rustbot author

[rustbot]

Error: shortcut handler unexpectedly failed in this comment: failed to remove Label { name: "S-waiting-on-review" }

Please file an issue on GitHub at triagebot if there's a problem with this bot, or reach out on #triagebot on Zulip.

[nikomatsakis]

Some drive-by comments.

[jackh726]

Okay, I have addressed the reviews to the best of my ability.

regarding moving divergence.md content elsewhere (#2067 (comment)):
I'm really not sure where else the remaining text can or should go. Importantly, this isn't a top-level chapter, it is under "Type system", which makes sense to me. It could be under some future "Type inference" sub-chapter, but that doesn't exist today and I'm not even sure.

regarding inlining other rules (#2067 (comment)):
I have no idea what is expected here.

regarding adding more examples:
I've added more examples over the course of addressing reviews, but if there are specific places that need more, I'm happy to respond specifically.

@rustbot review