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
+/// A utility macro for indicating unreachable code.
-/// executed. This is occasionally useful to put after loops that never
-/// terminate normally, but instead directly return from a function.
 ///
-/// # Example
+/// This is useful any time that the compiler can't determine that some code is unreachable. For
+/// example:
 ///
-/// ```{.rust}
+/// * Match arms with guard conditions.
-/// struct Item { weight: uint }
+/// * Loops that dynamically terminate.
+/// * Iterators that dynamically terminate.
 ///
-/// fn choose_weighted_item(v: &[Item]) -> Item {
+/// # Panics
-///     assert!(!v.is_empty());
+///
-///     let mut so_far = 0u;
+/// This will always panic.
-///     for item in v.iter() {
+///
-///         so_far += item.weight;
+/// # Examples
-///         if so_far > 100 {
+///
-///             return *item;
+/// Match arms:
-///         }
+///
+/// ```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!();
 /// }
 /// ```