rustdoc: Allow paths to (partially) be ignored in links

[orlp]

It's very common for me to refer to a particular method, function, struct, etc without wanting to mention the full path. Right now the easiest way to do this is as following:

/// See also [`my_long_function_name`](some::path::to::my_long_function_name).

This is really common in my experience (most often with Self as the path), and has three main problems:

1. It's annoying to repeat yourself.
2. It's error prone to repeat yourself, you could make a typo/refactor in one or the other causing them to go out of sync.
3. It's annoying to repeat yourself.

In this issue I would like to propose a simple shorthand for the above:

/// See also [some::path::to::`my_long_function_name`].

In essence, I propose that as a preprocessing step we transform Markdown links of the form

[ <PRIVATE_PATH> :: ` <PUBLIC_PATH> ` ]

into

[ ` <PUBLIC_PATH> ` ] ( <PRIVATE_PATH> :: <PUBLIC_PATH> )

This makes writing links a lot more convenient in general, and less error prone. Two more examples, also highlighting the possibility to partially ignore a path:

[foo::`bar`]        ->    [`bar`](foo::bar)
[foo::`bar::baz`]   ->    [`bar::baz`](foo::bar::baz)

[orlp]

For context, a simple backreferencing regex matching this usage pattern (\[`([^`]*)`]\([^)]*::\1\)) has 275 matches in rust-lang/rust, 91 matches in tokio, 203 matches in regex.

[lolbinarycat]

It's not ideal, but it is worth mentioning this is possible using a macro_rules! macro.

Additionally, how would you recommend this should look when using --document-private-items? What do you mean by "private path" here?

[orlp]

@lolbinarycat By "private" I simply mean the part of the path outside of the backticks:

[ <PRIVATE_PATH> :: ` <PUBLIC_PATH> ` ]

That is, it's purely syntactical, nothing based on pubness. I referred to it as private because it's not shown to the user in the link, unlike the public part. I understand that can be confused with pub, sorry about that.

So I believe [foo::`bar`] should interact with --document-private-items in exactly the same was as if you had written [`bar`](foo::bar). It's strictly syntactical shorthand.

[orlp]

I'd also like to note that this is functionally backwards compatible, just perhaps not cosmetically. Should this be implemented and adopted older versions of rustdoc will still resolve the correct paths to create the intra-links because that code currently strips backticks entirely. The only difference is that the older versions will output the somewhat ugly full path, partially in main body font, e.g. they will show:

See also some::path::to::my_long_function_name.