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.

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

@@ -538,6 +538,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
+