From 59653c10a6f6683f0c5fa4aab75fe01207a4fa21 Mon Sep 17 00:00:00 2001
From: Steve Klabnik <steve@steveklabnik.com>
Date: Thu, 27 Aug 2015 14:14:03 -0400
Subject: [PATCH] Some extra examples for the unimplemented! macro

---
 src/libcore/macros.rs | 45 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs
index 9f4d61a50d5..21038f25be3 100644
--- a/src/libcore/macros.rs
+++ b/src/libcore/macros.rs
@@ -254,6 +254,51 @@ macro_rules! unreachable {
 
 /// A standardised placeholder for marking unfinished code. It panics with the
 /// message `"not yet implemented"` when executed.
+///
+/// This can be useful if you are prototyping and are just looking to have your
+/// code typecheck, or if you're implementing a trait that requires multiple
+/// methods, and you're only planning on using one of them.
+///
+/// # Examples
+///
+/// Here's an example of some in-progress code. We have a trait `Foo`:
+///
+/// ```
+/// trait Foo {
+///     fn bar(&self);
+///     fn baz(&self);
+/// }
+/// ```
+///
+/// We want to implement `Foo` on one of our types, but we also want to work on
+/// just `bar()` first. In order for our code to compile, we need to implement
+/// `baz()`, so we can use `unimplemented!`:
+///
+/// ```
+/// # trait Foo {
+/// #     fn foo(&self);
+/// #     fn bar(&self);
+/// # }
+/// struct MyStruct;
+///
+/// impl Foo for MyStruct {
+///     fn foo(&self) {
+///         // implementation goes here
+///     }
+///
+///     fn bar(&self) {
+///         // let's not worry about implementing bar() for now
+///         unimplemented!();
+///     }
+/// }
+///
+/// fn main() {
+///     let s = MyStruct;
+///     s.foo();
+///
+///     // we aren't even using bar() yet, so this is fine.
+/// }
+/// ```
 #[macro_export]
 #[unstable(feature = "core",
            reason = "relationship with panic is unclear")]