Disambiguators are stripped off intra-doc link titles

[msix29]

rust-analyzer version: 0.3.1877-standalone (574e23e 2024-03-09)
rustc version: rustc 1.76.0 (07dca489a 2024-02-04)
relevant settings: Irrelevant to the issue.
repository link: luau-parser. Irrelevant to the issue.

code snippet to reproduce:

// This is an overly simplified version of it.

/// Some [function parameter](FunctionParameter)
pub struct FunctionParameter {}

Hover over FunctionParameters and read the doc comments, it displays:

The (reserved) keyword function is gone. I thought it was maybe because of the text being the same as that of the struct it's linking to, so for the sake of making sure, I tried another keyword:

/// Some [enum parameter](FunctionParameters)
pub struct FunctionParameters {}

And it gives exactly the same result. The word enum vanishes.

Some notes:

• The issue exists for inner doc comments too (//!).
• This is case sensitive; using Function or Enum makes it visible.
• This seems to work when having a different character there, for example function/parameter.
• It seems to work just fine with keywords like for and in, which means this may have been an intentional thing.

[lnicola]

Looks like we're stripping the disambiguators off the link text instead of the destination?

rust-analyzer/crates/ide/src/doc_links/intra_doc_links.rs

Line 16 in b6d1887

pub(super) fn parse_intra_doc_link(s: &str) -> (&str, Option<hir::Namespace>) {

EDIT: it's actually

rust-analyzer/crates/ide/src/doc_links.rs

Line 392 in b6d1887

Some((url.into(), strip_prefixes_suffixes(title).to_owned()))

.

[msix29]

That does look like it, looking at strip_prefixes_suffixes I thought adding a character would work, so to test that, I added a space ([ function parameters]) and surprisingly, it actually was visible and without the space at the start so I guess spaces are handled somewhere else (or maybe by native markup).

[lnicola]

Removing that single strip_prefixes_suffixes call doesn't cause any tests to fail, so I'm not sure what's up. Seems intentional though.

[msix29]

But wait, why's function even a disambiguator? Shouldn't it be fn?

Removing that single strip_prefixes_suffixes call doesn't cause any tests to fail, so I'm not sure what's up. Seems intentional though.

My only guess is to handle cases like struct@<name>. I think making sure there's a @ after it would fix everything? Because if there isn't one, that means it's more likely to be a normal word in the sentence.

[Veykril]

But wait, why's function even a disambiguator? Shouldn't it be fn?

rustdoc accepts a few more identifiers as disambiguators than just keywords, that's why. I wonder actually, should intra-doc links even be applicable in [...](...) form?

Removing that single strip_prefixes_suffixes call doesn't cause any tests to fail, so I'm not sure what's up. Seems intentional though.

Fwiw the tests are not very thorough, but I think we do the stripping there again because for just a [function foo] intra doc link, both target and title will be function foo, and the intra doc parsing only gets rid of the function _ in the target in that case.

[lnicola]

But wait, why's function even a disambiguator? Shouldn't it be fn?

No:

The following prefixes are available: struct, enum, trait, union, mod, module, const, constant, fn, function, method, derive, type, value, macro, prim or primitive.

I think we do the stripping there again because for just a [function foo] intra doc link, both target and title will be function foo

Maybe, but we also have tests like:

    check_rewrite(
        r#"
//- /main.rs crate:foo
/// [struct Foo](struct.Foo.html)
pub struct $0Foo;
"#,
        expect![[r#"[struct Foo](https://docs.rs/foo/*/foo/struct.Foo.html)"#]],
    );

[msix29]

Weird to see function and fn both being valid.

rustdoc accepts a few more identifiers as disambiguators than just keywords, that's why. I wonder actually, should intra-doc links even be applicable in [...](...) form?

Imo [...](...) form should be there, sometimes I prefer writing a sentence or a word that isn't actually the name of the item but rather something valid in the current context, which makes more sense when linked like so.

[Veykril]

Would be good to dive into rustdoc to see what the actual "specification" of intra doc links is. Iirc when this was implemented (I think that was me?) it was done with what could be found online which was not much

[lnicola]

I think it was zacps, about three years ago. Nvm, it's actually older.

[msix29]

Well, reading through The rustdoc book (sent by Inicola above), it says:

These prefixes will be stripped when displayed in the documentation, so [struct@Foo] will be rendered as Foo.

And

You can also disambiguate for functions by adding () after the function name, or for macros by adding ! after the macro name. The macro ! can be followed by (), {}, or [].

For the second one, I don't think any extra work needs to be done, but for the first, wouldn't what I Suggested above work?

I think making sure there's a @ after it would fix everything? Because if there isn't one, that means it's more likely to be a normal word in the sentence.