rustdoc: Allow paths to (partially) be ignored in links
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 119k
- Forks
- 16.1k
- PR merge metrics
- PR metrics pending
Description
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:
- It's annoying to repeat yourself.
- 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.
- 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)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in rustdoc's intra-doc link handling and trace how Markdown links are parsed and resolved. Compare the proposed [foo::bar] and [foo::bar::baz] forms with the existing explicit-label syntax, then add coverage showing that the rendered label is shortened while the full path remains the link target.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100