From ba02a9909b7e53245abe98981420ed721610b1ef Mon Sep 17 00:00:00 2001
From: mejrs <59372212+mejrs@users.noreply.github.com>
Date: Wed, 11 Oct 2023 00:02:06 +0200
Subject: [PATCH] Document `diagnostic_namespace` feature

---
 .../language-features/diagnostic-namespace.md | 84 +++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 src/doc/unstable-book/src/language-features/diagnostic-namespace.md

diff --git a/src/doc/unstable-book/src/language-features/diagnostic-namespace.md b/src/doc/unstable-book/src/language-features/diagnostic-namespace.md
new file mode 100644
index 0000000000000..7c46811a27ab8
--- /dev/null
+++ b/src/doc/unstable-book/src/language-features/diagnostic-namespace.md
@@ -0,0 +1,84 @@
+# `diagnostic_namespace`
+
+The tracking issue for this feature is: [#111996]
+
+[#111996]: https://github.com/rust-lang/rust/issues/111996
+
+------------------------
+
+The `diagnostic_namespace` feature permits customization of compilation errors.
+
+## diagnostic::on_unimplemented
+
+With [#114452] support for `diagnostic::on_unimplemented` was added.
+
+When used on a trait declaration, the following options are available:
+
+* `message` to customize the primary error message
+* `note` to add a customized note message to an error message
+* `label` to customize the label part of the error message
+
+The attribute will hint to the compiler to use these in error messages:
+```rust
+// some library
+#![feature(diagnostic_namespace)]
+
+#[diagnostic::on_unimplemented(
+    message = "cannot insert element",
+    label = "cannot be put into a table",
+    note = "see <link> for more information about the Table api"
+)]
+pub trait Element {
+    // ...
+}
+```
+
+```rust,compile_fail,E0277
+# #![feature(diagnostic_namespace)]
+#
+# #[diagnostic::on_unimplemented(
+#    message = "cannot insert element",
+#    label = "cannot be put into a table",
+#    note = "see <link> for more information about the Table api"
+# )]
+# pub trait Element {
+#    // ...
+# }
+# struct Table;
+# impl Table {
+#    fn insert<T: Element>(&self, element: T) {
+#        // ..
+#    }
+# }
+# fn main() {
+#    let table = Table;
+#    let element = ();
+// user code
+table.insert(element);
+# }
+```
+
+```text
+error[E0277]: cannot insert element
+  --> src/main.rs:24:18
+   |
+24 |     table.insert(element);
+   |           ------ ^^^^^^^ cannot be put into a table
+   |           |
+   |           required by a bound introduced by this call
+   |
+   = help: the trait `Element` is not implemented for `<type>`
+   = note: see <link> for more information about the Table api
+note: required by a bound in `Table::insert`
+  --> src/main.rs:15:18
+   |
+15 |     fn insert<T: Element>(&self, element: T) {
+   |                  ^^^^^^^ required by this bound in `Table::insert`
+
+For more information about this error, try `rustc --explain E0277`.
+```
+
+See [RFC 3368] for more information.
+
+[#114452]: https://github.com/rust-lang/rust/pull/114452
+[RFC 3368]: https://github.com/rust-lang/rfcs/blob/master/text/3368-diagnostic-attribute-namespace.md