rustdoc: Link references are case-insensitive

[ericseppanen]

EDIT(camelid): This is not an intra-doc links issue. See #80882 (comment).

---

I found a glitch in the std/core library docs. The docs for PartialEq contain this snippet:

/// This trait allows for partial equality, for types that do not have a full
/// equivalence relation. For example, in floating point numbers `NaN != NaN`,
/// so floating point types implement `PartialEq` but not [`Eq`].

At present, the Eq link has the wrong target, because rustdoc links it to the method eq instead.

I sent a PR that forces the correct linkage (#80864) for this instance, but perhaps rustdoc could be smarter here?

On that PR @jyn514 writes:

This is a bug in rustdoc for several reasons:

• It shouldn't treat identifiers as case-insensitive
• It should give a warning if the link is ambiguous

[jyn514]

@ericseppanen do you have time to make a smaller reproduction than the standard library? No problem if not, I just won't get around to it for a while.

[ericseppanen]

Sure, I'll give it a try!

[ericseppanen]

Everything works correctly under these cases:

• trait Foo and freestanding function foo
• trait Foo and impl Foo { fn foo() {} }
• trait Bar docs link to trait Foo, with a similarly named fn foo()

After staring at the PartialEq example in the standard library, I was able to reproduce the problem: we need an explicit link target specified at the end for the lowercase member fn. I think this is called a "link reference definition"?

This example shows the problem: the doc page for Bar has the wrong link target for Foo.

/// The `Bar` trait.
///
/// - Here is another trait: [`Foo`]
/// - Here is our similarly-named member fn: [`foo`]
///
/// [`foo`]: Bar::foo
///
pub trait Bar {
    /// The fn `foo` from the trait `Bar`
    fn foo();
}

/// This is the `Foo` trait.
pub trait Foo {}

[ericseppanen]

I can also make it broken in the opposite direction. If I replace it with

/// [`Foo`]: Foo

Then both links change. I.e. [`foo`] now links to Foo.

So the problem seems to be that link reference definitions are case-insensitive, and take over links to differently-cased names.

[camelid]

Darn, I'm pretty sure the issue is that pulldown-cmark treats link references as case-insensitive. I'm not sure what the standard is supposed to be though and I'm not sure if there's anything we can do it. We might be able to convince them to add an option to treat them as case-sensitive, but even then it might cause a lot of breakage for us.

By the way, you can see that it's not an intra-doc link issue with this code:

//! [foo]
//!
//! [FOO]: https://example.com

foo will be resolved to example.com.

[camelid]

@ericseppanen Thanks for debugging this!

[bugadani]

https://spec.commonmark.org/dingus/?text=%5Bfoo%5D%0A%0A%5BFOO%5D%3A%20https%3A%2F%2Fexample.com

The CommonMark reference implementation handles link references case insensitive.

As per the spec labels are case insensitive.

[jyn514]

I'm not sure what the standard is supposed to be though and I'm not sure if there's anything we can do it. We might be able to convince them to add an option to treat them as case-sensitive, but even then it might cause a lot of breakage for us.

That indeed looks like the issue :/ https://daringfireball.net/projects/markdown/syntax#link

Link definition names may consist of letters, numbers, spaces, and punctuation — but they are not case sensitive.

I don't know what we can do about this, other than to document that this is a footgun. @Manishearth what do you think?