diff --git a/src/doc/reference.md b/src/doc/reference.md
index 2486466c8696d..62b922ea4beac 100644
--- a/src/doc/reference.md
+++ b/src/doc/reference.md
@@ -2117,6 +2117,13 @@ macro scope.
   destructors from being run twice. Destructors might be run multiple times on
   the same object with this attribute.
 - `doc` - Doc comments such as `/// foo` are equivalent to `#[doc = "foo"]`.
+- `rustc_on_unimplemented` - Write a custom note to be shown along with the error
+   when the trait is found to be unimplemented on a type.
+   You may use format arguments like `{T}`, `{A}` to correspond to the
+   types at the point of use corresponding to the type parameters of the
+   trait of the same name. `{Self}` will be replaced with the type that is supposed
+   to implement the trait but doesn't. To use this, the `on_unimplemented` feature gate
+   must be enabled.
 
 ### Conditional compilation
 
diff --git a/src/test/compile-fail/on-unimplemented-bad-anno.rs b/src/test/compile-fail/on-unimplemented-bad-anno.rs
index 3bd3f517dbccd..dda534cc489b5 100644
--- a/src/test/compile-fail/on-unimplemented-bad-anno.rs
+++ b/src/test/compile-fail/on-unimplemented-bad-anno.rs
@@ -29,6 +29,9 @@ trait BadAnnotation1 {}
 //~^ ERROR there is no type parameter C on trait BadAnnotation2
 trait BadAnnotation2<A,B> {}
 
+#[rustc_on_unimplemented = "Unimplemented trait error on `{Self}` with params `<{A},{B},{}>`"]
+//~^ only named substitution parameters are allowed
+trait BadAnnotation3<A,B> {}
 
 pub fn main() {
 }