There has been some ongoing confusion regarding when to use llvm_unreachable which this patch attempts to address. Specifically, the confusion has been around whether llvm_unreachable is intended to mark only unreachable code paths that the compiler cannot determine itself or to mark a code path which is unconditionally a bug to reach. Based on email and IRC discussions, it sounds like "unconditional bug to reach" is the consensus.
ah, good to see there's already some verbiage here that covers the general idea (which I'd clearly forgotten about, might've been good framing for the discussion earlier, so good to know it's here) - specifically saying "here's a better thing" but "use it" is left as an implication - the new paragraph makes that more explicit, which is good.
Thanks a bunch!