mirror of
https://github.com/rust-lang/rust.git
synced 2024-11-28 09:44:08 +00:00
0035d9dcec
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. |
||
|---|---|---|
| .. | ||
| src | ||
| Cargo.toml | ||