Change:
($($arg:tt)*) => (if cfg!(not(ndebug)) { assert_eq!($($arg)*); }) ) <del> /// A utility macro for indicating unreachable code. It will panic if /// executed. This is occasionally useful to put after loops that never /// terminate normally, but instead directly return from a function. </del> <ins> /// A utility macro for indicating unreachable code. </ins> /// <del> /// # Example </del> <ins> /// This is useful any time that the compiler can't determine that some code is unreachable. For /// example: /// /// * Match arms with guard conditions. /// * Loops that dynamically terminate. /// * Iterators that dynamically terminate. /// /// # Panics /// /// This will always panic. /// /// # Examples /// /// Match arms: </ins> /// <del> /// ```{.rust} /// struct Item { weight: uint } /// /// fn choose_weighted_item(v: &[Item]) -> Item { ///     assert!(!v.is_empty()); ///     let mut so_far = 0u; ///     for item in v.iter() { ///         so_far += item.weight; ///         if so_far > 100 { ///             return *item; ///         } </del> <ins> /// ```rust /// fn foo(x: Option<int>) { ///    match x { ///     Some(n) if n >= 0 => println!("Some(Non-negative)"), ///     Some(n) if n <  0 => println!("Some(Negative)"), ///     Some(_)           => unreachable!(), // compile error if commented out ///     None              => println!("None") /// } /// ``` /// /// Iterators: /// /// ```rust /// fn divide_by_three(x: i32) -> i32 { // one of the poorest implementations of x/3 ///     for i in std::iter::count(0_i32, 1) { ///         if i < 0 { panic!("i32 overflow"); } ///         if x < 3*i { return i; } </ins> ///     } <del> ///     // The above loop always returns, so we must hint to the ///     // type checker that it isn't possible to get down here </del> <ins> /// </ins> ///     unreachable!(); /// } /// ```

Discussion:
At present, the documentation for has an example where you could not argue that the 'unreachable' code is indeed unreachable: I would argue a better example would see a loop more like: Perhaps I am miss understanding the purpose of this macro, in the example I provided here, is the compiler able to determine that the loop will keep going until eventually the is executed, and thus there is no need for the . In which case, I think the documentation should make it clear that in such situations the macro is not required. I'd argue it is as important to know where not to use this macro as it is when to use it.
This example certainly is more complicated than it has to be.
. Rust understands that is forever.
is for asserting that while technically the control flow can reach this block of code, it would be a logic error for this to occur. The most common usage I know is for a pattern match which has some logical constraints that can't be expressed by the type system. For example this simple function in : Here we are asserting that the program is in an inconsistent state if both removes yield anything other than . Similarly you would use after a loop if the program is incorrect if the loop terminates normally.
do you mean the example in the documentation or my proposed example is overly complicated? ah, I see what it's purpose is now then. Perhaps the documentation should make it clear that there is no need to mark code that that literally cannot be reached, only code which shouldn't be reached. I think your example is much nicer as it shows a more real world example of where this macro should be used.
The exam;ple in the documentation.
On Reddit I learned exhaustiveness check can't understand match guards and we sometimes need to insert a seemingly unnecessary arm with wildcard pattern. Iterator utilities sometimes need :