Auto merge of #87050 - jyn514:no-doc-primitive, r=manishearth

Add future-incompat lint for `doc(primitive)`

## What is `doc(primitive)`?

`doc(primitive)` is an attribute recognized by rustdoc which adds documentation for the built-in primitive types, such as `usize` and `()`. It has been stable since Rust 1.0.

## Why change anything?

`doc(primitive)` is useless for anyone outside the standard library. Since rustdoc provides no way to combine the documentation on two different primitive items, you can only replace the docs, and since the standard library already provides extensive documentation there is no reason to do so.

While fixing rustdoc's handling of primitive items (https://github.com/rust-lang/rust/pull/87073) I discovered that even rustdoc's existing handling of primitive items was broken if you had more than two crates using it (it would pick randomly between them). That meant both:
- Keeping rustdoc's existing treatment was nigh-impossible, because it was random.
- doc(primitive) was even more useless than it would otherwise be.

The only use-case for this outside the standard library is for no-std libraries which want to link to primitives (https://github.com/rust-lang/rust/issues/73423) which is being fixed in https://github.com/rust-lang/rust/pull/87073.

https://github.com/rust-lang/rust/pull/87073 makes various breaking changes to `doc(primitive)` (breaking in the sense that they change the semantics, not in that they cause code to fail to compile). It's not possible to avoid these and still fix rustdoc's issues.

## What can we do about it?

As shown by the crater run (https://github.com/rust-lang/rust/pull/87050#issuecomment-886166706), no one is actually using doc(primitive), there wasn't a single true regression in the whole run. We can either:
1. Feature gate it completely, breaking anyone who crater missed. They can easily fix the breakage just by removing the attribute.
2. add it to the `INVALID_DOC_ATTRIBUTES` future-incompat lint, and at the same time make it a no-op unless you add a feature gate. That would mean rustdoc has to look at the features of dependent crates, because it needs to know where primitives are defined in order to link to them.
3. add it to `INVALID_DOC_ATTRIBUTES`, but still use it to determine where primitives come from
4. do nothing; the behavior will silently change in https://github.com/rust-lang/rust/pull/87073.

My preference is for 2, but I would also be happy with 1 or 3. I don't think we should silently change the behavior.

This PR currently implements 3.

9 files changed, 49 insertions, 7 deletions

diff --git a/compiler/rustc_feature/src/active.rs b/compiler/rustc_feature/src/active.rs
index 73b29d65e91..56dac253c54 100644
--- a/compiler/rustc_feature/src/active.rs
+++ b/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
     // -------------------------------------------------------------------------
diff --git a/compiler/rustc_passes/src/check_attr.rs b/compiler/rustc_passes/src/check_attr.rs
index 7cca11f20bb..1bb6b899875 100644
--- a/compiler/rustc_passes/src/check_attr.rs
+++ b/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,
diff --git a/compiler/rustc_span/src/symbol.rs b/compiler/rustc_span/src/symbol.rs
index 62719ab1ab6..f788eb7d212 100644
--- a/compiler/rustc_span/src/symbol.rs
+++ b/compiler/rustc_span/src/symbol.rs
@@ -538,6 +538,7 @@ symbols! {
         doc_keyword,
         doc_masked,
         doc_notable_trait,
+        doc_primitive,
         doc_spotlight,
         doctest,
         document_private_items,
diff --git a/library/std/src/lib.rs b/library/std/src/lib.rs
index 861a6fc193c..43db3f91022 100644
--- a/library/std/src/lib.rs
+++ b/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)]
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
+