Improve documentation for unreachable

Fixes #18876

src/libstd/macros.rs

@@ -186,26 +186,42 @@ macro_rules! debug_assert_eq(
     ($($arg:tt)*) => (if cfg!(not(ndebug)) { assert_eq!($($arg)*); })
 )
 
-/// 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.
+/// A utility macro for indicating unreachable code.
 ///
-/// # Example
+/// 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:
 ///
-/// ```{.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;
-///         }
+/// ```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; }
 ///     }
-///     // The above loop always returns, so we must hint to the
-///     // type checker that it isn't possible to get down here
+///
 ///     unreachable!();
 /// }
 /// ```