Add basic Unstable Book entry for `on_unimplemented`.

diff --git a/src/doc/unstable-book/src/language-features/on-unimplemented.md b/src/doc/unstable-book/src/language-features/on-unimplemented.md
index 81f284d0a6a3e0bb52573dd92ba162ea2ebb2d3a..9eea3fccbbc17e39ad591fb72f94893f0027d5f5 100644 (file)
--- a/src/doc/unstable-book/src/language-features/on-unimplemented.md
+++ b/src/doc/unstable-book/src/language-features/on-unimplemented.md
@@ -6,5 +6,42 @@ The tracking issue for this feature is: [#29628]
 
 ------------------------
 
+The `on_unimplemented` feature provides the `#[rustc_on_unimplemented]`
+attribute, which allows trait definitions to add specialized notes to error
+messages when an implementation was expected but not found.
 
+For example:
+
+```rust,compile_fail
+#![feature(on_unimplemented)]
+
+#[rustc_on_unimplemented="a collection of type `{Self}` cannot be built from an \
+                          iterator over elements of type `{A}`"]
+trait MyIterator<A> {
+    fn next(&mut self) -> A;
+}
+
+fn iterate_chars<I: MyIterator<char>>(i: I) {
+    // ...
+}
+
+fn main() {
+    iterate_chars(&[1, 2, 3][..]);
+}
+```
+
+When the user compiles this, they will see the following;
+
+```txt
+error[E0277]: the trait bound `&[{integer}]: MyIterator<char>` is not satisfied
+  --> <anon>:14:5
+   |
+14 |     iterate_chars(&[1, 2, 3][..]);
+   |     ^^^^^^^^^^^^^ the trait `MyIterator<char>` is not implemented for `&[{integer}]`
+   |
+   = note: a collection of type `&[{integer}]` cannot be built from an iterator over elements of type `char`
+   = note: required by `iterate_chars`
+
+error: aborting due to previous error
+```