rustdoc: Can't use anchors in links to primitive types

[taylordotfish]

rustdoc doesn't allow anchors in links to primitive types. For example, given this code:

//! [test](str#examples)

cargo doc produces this warning:

warning: `str#examples` contains an anchor, but links to builtin types are already anchored
 --> src/lib.rs:1:12
  |
1 | //! [test](str#examples)
  |            ^^^^^^^^^^^^ contains invalid anchor
  |
  = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default

and the resulting link doesn't point to any part of str's documentation, but is rather treated as a normal URL relative to the current page.

The warning claims that “links to builtin types are already anchored”, but this does not appear to be correct. For example, this code:

//! [test](str)

produces a link to https://doc.rust-lang.org/nightly/std/primitive.str.html, which does not contain an anchor.

Meta

rustc 1.52.0-nightly (b3e19a221 2021-03-12)
binary: rustc
commit-hash: b3e19a221e63dcffdef87e12eadf1f36a8b90295
commit-date: 2021-03-12
host: powerpc64le-unknown-linux-gnu
release: 1.52.0-nightly
LLVM version: 12.0.0

[jyn514]

This was first made an error in 454d13b. At that point there was a comment saying "TODO: give an error", which was first added in 09293be.

@GuillaumeGomez do you remember why you made this an error? #66675 was released in 1.41.0, which still uses the primitive.str.html URL scheme.

[GuillaumeGomez]

I think I had in mind that the anchors weren't stable and that it wasn't "safe" to use anchors on primitive for this reason. Not sure if it makes much sense though considering we allow it for foreign types...

[jyn514]

Oh, I found why this restriction is here:

rust/src/librustdoc/passes/collect_intra_doc_links.rs

Lines 238 to 243 in acca818

	/// Most of the time this is fine, because you can just link to the page of
	/// the item if you want to provide your own anchor. For primitives, though,
	/// rustdoc uses the anchor as a side channel to know which page to link to;
	/// it doesn't show up in the generated link. Ideally, rustdoc would remove
	/// this limitation, allowing you to link to subheaders on primitives.
	RustdocAnchorConflict(Res),

I'm ambivalent whether this should be considered a bug or a feature request; happy for anyone to try and fix it but it won't be trivial. The fragment is used here:

rust/src/librustdoc/passes/collect_intra_doc_links.rs

Line 1252 in acca818

Some(ItemLink { link: ori_link.link, link_text, did: None, fragment })

and later here:

rust/src/librustdoc/clean/types.rs

Lines 873 to 902 in acca818

	if let Some(ref fragment) = *fragment {
	let url = match cache.extern_locations.get(&krate) {
	Some(&(_, _, ExternalLocation::Local)) => {
	let depth = CURRENT_DEPTH.with(|l| l.get());
	"../".repeat(depth)
	}
	Some(&(_, _, ExternalLocation::Remote(ref s))) => s.to_string(),
	Some(&(_, _, ExternalLocation::Unknown)) | None => String::from(
	// NOTE: intentionally doesn't pass crate name to avoid having
	// different primitive links between crates
	if UnstableFeatures::from_environment(None).is_nightly_build() {
	"https://doc.rust-lang.org/nightly"
	} else {
	"https://doc.rust-lang.org"
	},
	),
	};
	// This is a primitive so the url is done "by hand".
	let tail = fragment.find('#').unwrap_or_else(|| fragment.len());
	Some(RenderedLink {
	original_text: s.clone(),
	new_text: link_text.clone(),
	href: format!(
	"{}{}std/primitive.{}.html{}",
	url,
	if !url.ends_with('/') { "/" } else { "" },
	&fragment[..tail],
	&fragment[tail..]
	),
	})

[jyn514]

This would be a good use case for my 'fake DefId' idea: https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/getting.20rid.20of.20cell.20and.20refcell.20usage/near/225222711