Rust: Resolve intra-doc-links on Self type implicitly

[Manishearth]

With intra-doc-links, the following works:

/// [Self::bar]
pub struct Foo;

impl Foo {
    /// [Self::bar]
    fn bar() {}
}

but this does not:

/// [bar]
pub struct Foo;

impl Foo {
    /// [bar]
    fn bar() {}
}

For structs and impls we should try resolving things against Self anyway

[Centril]

Are you saying [bar] should work? If so, what if there's a free function bar in the module that's defined next to Foo?

[petrochenkov]

I'd rather stick to the language rules if possible than create a subtly different dialect working only in rustdoc links.

[Manishearth]

Pick the function first, if it exists, and if not look for the method. You can always disambiguate with full paths.

I don't see how this is a problem, intra doc links already does a bunch of fallbacky things, this would be another.

I'd rather stick to the language rules if possible.

I was going through intra doc failures in servo's deps (debugging a rustdoc regression and in the process noticing warnings) and it's common for people to do this and expect it to work already. It's a pretty common use case; method and type docs cross link to other methods all the time. We should support it.

I don't see why intra doc links (which already have a bunch of special syntax) should stick to the language rules.

[Manishearth]

(This may need an RFC, though, but it's worth getting it on file somewhere)

[Centril]

I don't see why intra doc links (which already have a bunch of special syntax) should stick to the language rules.

I think it could create confusion as to what the language rules are for some users. Such confusion will cease when users actually try bar and find that it doesn't work but it's still a surprise. Seems like a trade-offs to make between temporarily breaking mental models vs. convenience. You could argue that not having [bar] is the surprising behavior tho per "expect it to work already". Do we have more cases of where intra-doc-links do/should diverge from the language rules?

[Manishearth]

I disagree that intra-doc-links are fundamentally viewed as paths in the same way. The main use case is to name types and methods (so, rarely full paths, usually Type and Type::method), to me the mental model is that it's a markdown link that autoreferences the relevant type if it can find one, and being able to find one is a best-effort thing. If you type [bar] you're saying "link me to bar", and the tool should be smart enough to understand what you mean. You are not saying "resolve bar in scope", that is how it works at the moment but I don't think it has to, nor do I think this is the mental model we should push for this feature.

This is the same kind of magic as doctests, IMO: nobody sees doctests and assumes that there's a way to write Rust programs without a main(). The documentation isn't code, I don't expect to see assumptions like this leaking through to code.

And yeah, like I said, people are trying this already! (I'll have to look for the crates again)

[Manishearth]

Actually I think the best way to look at intra doc links is that if you're doing [`blah`](somelink) you should be able to omit the somelink in as many cases as possible

[Centril]

@Manishearth You make a good case overall. I still think there's a bit of a risk for some users, but it may be small enough to not matter in the grand scheme. An RFC sounds like a good place to flesh it all out.

[Manishearth]

Sounds good. Might open one, depending on what the docs team feels about this feature overall.

[ehuss]

Note to anyone that might be confused, the original example of /// [Self::bar] on a method does not work. It only works on the struct definition. The example presumably does not show any warnings because the method is private. See #70802.

[jyn514]

@rustbot modify labels: C-enhancement

[pickfire]

I don't know if Self would be good but I think using the parent module would be good since it is quite common to do env::arg. In the docs, this will align with the parent item import.