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.

[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.

[clarfonthey]

Copying over what I said in a dupe issue since despite looking over every issue tagged intra-doc-links I missed this one:

I think if there's any ambiguity, there should be a lint to request you state self::item or Self::item to resolve the ambiguity. We should probably default to the former since it's the current behaviour.

[chrysn]

A pattern of documentation I frequently find myself writing is

This also influences what [`.get()`][Self::get] does

This has fewer risks of ambiguity, and fits with the language rules -- spoken language has more context than a programming language, and in the docs of something that can have members, self would be a logical subject.

As a whole, is this issue still in the state where the next step is an RFC to flesh out precise rules?

[jyn514]

. anywhere in a link means it won’t even be seen by rustdoc, because the markdown parser interprets it as a url.

[Manishearth]

@jyn514 iirc that's not the case: it's a parser controlled by us that does this, but it has a quick-reject heuristic that uses . and so far it has not needed to support anything actually ambiguous with a URL. (I think)

[Manishearth]

I think this is the code that parses links, looks like it doesn't treat . specially anyway

rust/src/librustdoc/passes/collect_intra_doc_links.rs

Lines 879 to 891 in f79fae3

	fn preprocess_link(
	ori_link: &MarkdownLink,
	dox: &str,
	) -> Option<Result<PreprocessingInfo, PreprocessingError>> {
	// [] is mostly likely not supposed to be a link
	if ori_link.link.is_empty() {
	return None;
	}
	// Bail early for real links.
	if ori_link.link.contains('/') {
	return None;
	}