`f16` creates doc-link ambiguity on stable

[kpreid]

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.

[Noratrieb]

What's the behavior for f32?

[kpreid]

The same:

warning: `f32` is both a struct and a primitive type
 --> src/lib.rs:4:22
  |
4 | /// Blah blah blah [`f32`]
  |                      ^^^ 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@f32`]
  |                      +++++++
help: to link to the primitive type, prefix with `prim@`
  |
4 | /// Blah blah blah [`prim@f32`]
  |                      +++++

However, this is inappropriate behavior for any newly introduced item (and thus, arguably, all of them for consistency) because it means future prelude additions can break existing code’s documentation. Arguably the problem is that rustdoc is making finer distinctions than the language’s namespace system, whereas it should make exactly the same distinctions and respect shadowing.

But that’s more of a concern on principle. The important part of this is that unstable f16 is affecting the behavior of stable Rust. (I found this problem while trying to make a contribution to half, whose entire point is to define a type named f16.)

@rustbot label +T-rustdoc +A-intra-doc-links