Additions to the standard library prelude may break user intra-doc links (due to newly introduced ambiguity)
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 119k
- Forks
- 16.1k
- PR merge metrics
- PR metrics pending
Description
I cargo doced this code:
#[allow(non_camel_case_types)]
pub struct f16 {}
/// Blah blah blah [`f16`]
pub fn foo() -> f16 {
f16 {}
}
I got:
warning: `f16` is both a struct and a primitive type
--> src/lib.rs:4:22
|
4 | /// Blah blah blah [`f16`]
| ^^^ ambiguous link
|
= note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default
help: to link to the struct, prefix with `struct@`
|
4 | /// Blah blah blah [`struct@f16`]
| +++++++
help: to link to the primitive type, prefix with `prim@`
|
4 | /// Blah blah blah [`prim@f16`]
and the link was missing in the generated documentation. Instead, because f16 is unstable, it should have no effect and there should be no warning.
Additionally, even when f16 is stable, the link should not be considered ambiguous since primitive f16 is being shadowed. (Otherwise, currently valid code will get broken links when f16 stabilizes.)
Meta
rustc --version --verbose:
rustc 1.86.0-nightly (ed43cbcb8 2025-01-21)
binary: rustc
commit-hash: ed43cbcb882e7c06870abdd9305dc1f17eb9bab9
commit-date: 2025-01-21
host: aarch64-apple-darwin
release: 1.86.0-nightly
LLVM version: 19.1.7
Also occurs on stable 1.84.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the warning with the minimal example in src/lib.rs by running cargo doc, then investigate rustdoc's intra-doc link resolution for the prelude's unstable and shadowed f16 names. Done means the example produces no warning or missing link while preserving the intended link behavior when the primitive is stable.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- compilers, documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100