rust-lang / rust-lang/rust

Additions to the standard library prelude may break user intra-doc links (due to newly introduced ambiguity)

Open
#135,897 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-intra-doc-links C-bug T-rustdoc
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.