feature gate doc(primitive)

5 files changed, 28 insertions, 6 deletions

diff --git a/src/doc/rustdoc/src/the-doc-attribute.md b/src/doc/rustdoc/src/the-doc-attribute.md
index d192f7d5ce9..b17ea7cd8f5 100644
--- a/src/doc/rustdoc/src/the-doc-attribute.md
+++ b/src/doc/rustdoc/src/the-doc-attribute.md
@@ -223,9 +223,3 @@ not eagerly inline it as a module unless you add `#[doc(inline)]`.
 
 Any item annotated with `#[doc(hidden)]` will not appear in the documentation, unless
 the `strip-hidden` pass is removed.
-
-## `#[doc(primitive)]`
-
-Since primitive types are defined in the compiler, there's no place to attach documentation
-attributes. This attribute is used by the standard library to provide a way to generate
-documentation for primitive types.
diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md
index e9b15666bb3..dce98abcf53 100644
--- a/src/doc/rustdoc/src/unstable-features.md
+++ b/src/doc/rustdoc/src/unstable-features.md
@@ -131,6 +131,13 @@ Book][unstable-masked] and [its tracking issue][issue-masked].
 [unstable-masked]: ../unstable-book/language-features/doc-masked.html
 [issue-masked]: https://github.com/rust-lang/rust/issues/44027
 
+
+## Document primitives
+
+Since primitive types are defined in the compiler, there's no place to attach documentation
+attributes. The `#[doc(primitive)]` attribute is used by the standard library to provide a way to generate
+documentation for primitive types, and requires `#![feature(doc_primitive)]` to enable.
+
 ## Unstable command-line arguments
 
 These features are enabled by passing a command-line flag to Rustdoc, but the flags in question are
diff --git a/src/test/rustdoc-ui/coverage/exotic.rs b/src/test/rustdoc-ui/coverage/exotic.rs
index 281ce571aa0..18f2014d9e4 100644
--- a/src/test/rustdoc-ui/coverage/exotic.rs
+++ b/src/test/rustdoc-ui/coverage/exotic.rs
@@ -2,6 +2,7 @@
 // check-pass
 
 #![feature(doc_keyword)]
+#![feature(doc_primitive)]
 
 //! the features only used in std also have entries in the table, so make sure those get pulled out
 //! properly as well
diff --git a/src/test/ui/rustdoc/feature-gate-doc_primitive.rs b/src/test/ui/rustdoc/feature-gate-doc_primitive.rs
new file mode 100644
index 00000000000..18e99e72f8b
--- /dev/null
+++ b/src/test/ui/rustdoc/feature-gate-doc_primitive.rs
@@ -0,0 +1,8 @@
+// check-pass
+#[doc(primitive = "usize")]
+//~^ WARNING `doc(primitive)` should never have been stable
+//~| WARNING hard error in a future release
+/// Some docs
+mod usize {}
+
+fn main() {}
diff --git a/src/test/ui/rustdoc/feature-gate-doc_primitive.stderr b/src/test/ui/rustdoc/feature-gate-doc_primitive.stderr
new file mode 100644
index 00000000000..736bf29c580
--- /dev/null
+++ b/src/test/ui/rustdoc/feature-gate-doc_primitive.stderr
@@ -0,0 +1,12 @@
+warning: `doc(primitive)` should never have been stable
+  --> $DIR/feature-gate-doc_primitive.rs:2:7
+   |
+LL | #[doc(primitive = "usize")]
+   |       ^^^^^^^^^^^^^^^^^^^
+   |
+   = note: `#[warn(invalid_doc_attributes)]` on by default
+   = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
+   = note: for more information, see issue #82730 <https://github.com/rust-lang/rust/issues/82730>
+
+warning: 1 warning emitted
+