rewrite never type documentation

[WaffleLapkin]

With the never type stabilization approaching, I think the documentation could be improved a lot over the status quo ^^'

I intend to merge this after #155499. Split it off into a separate PR for ease of reviewing.

[kpreid]

I saw some typos, so here’s a batch of copyediting suggestions (also some for jargon clarification). Feel free to ignore these if not useful.

View changes since this review

[kpreid]

Suggested change

	/// // allowing the `match` to typecheck
	/// // allowing the `match` to pass type checking.

[WaffleLapkin]

Hm, I prefer "to typecheck", do you think this is too jargony?

[kpreid]

Ehhhh vague hand gestures only kind of. As a general matter of how I see people failing to understanding things, I think that programming jargon often has what I call a “noun pileup” problem: squeezing all the meaning into a single noun phrase (or verb, in this case) that lacks any structure to indicate what its parts are referring to if you don’t already know. This suggestion was an attempt, not to fix a definite problem, but to improve the average.

In particular, it add an indication (“pass”) that “type checking” is something done to the match, whereas “typecheck” as a verb whose subject is match could point towards more incorrect theories such as “the match is (at run time) checking that the type of the arm matches the type that is needed”. Does that disagree with how Rust works in general? Yes. But the people who need this documentation won’t necessarily know that, so adding more clues towards the right reading helps learning go more smoothly.

But, just like I said for the rest of these, feel free to disregard this suggestion. It’s a guess at what will be more clear.

[poseidon-rises]

If I can throw my two cents in, I think "pass type checking" reads smoother, something about "...allowing the match to typecheck." just feels clunky.