feature gate doc(primitive)

compiler/rustc_feature/src/active.rs

@@ -682,6 +682,9 @@ declare_features! (
     /// Allows explicit generic arguments specification with `impl Trait` present.
     (active, explicit_generic_args_with_impl_trait, "1.56.0", Some(83701), None),
 
+    /// Allows using doc(primitive) without a future-incompat warning
+    (active, doc_primitive, "1.56.0", Some(88070), None),
+
     // -------------------------------------------------------------------------
     // feature-group-end: actual feature gates
     // -------------------------------------------------------------------------

compiler/rustc_passes/src/check_attr.rs

@@ -794,9 +794,24 @@ impl CheckAttrVisitor<'tcx> {
                         | sym::notable_trait
                         | sym::passes
                         | sym::plugins
-                        | sym::primitive
                         | sym::test => {}
 
+                        sym::primitive => {
+                            if !self.tcx.features().doc_primitive {
+                                self.tcx.struct_span_lint_hir(
+                                    INVALID_DOC_ATTRIBUTES,
+                                    hir_id,
+                                    i_meta.span,
+                                    |lint| {
+                                        let mut diag = lint.build(
+                                            "`doc(primitive)` should never have been stable",
+                                        );
+                                        diag.emit();
+                                    },
+                                );
+                            }
+                        }
+
                         _ => {
                             self.tcx.struct_span_lint_hir(
                                 INVALID_DOC_ATTRIBUTES,

compiler/rustc_span/src/symbol.rs

@@ -513,6 +513,7 @@ symbols! {
         doc_keyword,
         doc_masked,
         doc_notable_trait,
+        doc_primitive,
         doc_spotlight,
         doctest,
         document_private_items,

library/std/src/lib.rs

@@ -263,6 +263,7 @@
 #![feature(doc_keyword)]
 #![feature(doc_masked)]
 #![feature(doc_notable_trait)]
+#![cfg_attr(not(bootstrap), feature(doc_primitive))]
 #![feature(dropck_eyepatch)]
 #![feature(duration_checked_float)]
 #![feature(duration_constants)]

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.

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

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

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() {}

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
+