rustdoc: make linking to examples easier and detect dead links

[alice-i-cecile]

When writing module-level or other high-level documentation, I often want to link to our examples to show users how to do something in more detail. See bevyengine/bevy#15056 for an example of this problem.

This is distinct from the automatically generated links to examples, rustdoc-scrape-examples, (which are great!): we want to be able to manually link to specific examples.

@GuillaumeGomez pointed out that this can be done in part using relative paths, e.g. ../../src/custom_loop/custom_loop.rs.html#19. However, this is very fragile: any change to either file breaks the link with no tooling to detect the breakage. This functionality is also undocumented, and could be broken by rustdoc / docs.rs at any time.

To add full support, he thinks we might need an intra-doc link extension to make it work.

[GuillaumeGomez]

I think the best course of action here would be to extend intra-doc links and give them possibility to link to an example. My best idea at the moment is to the prepend the example path with example:. It would look like this:

/// Oh what a nice [example][example:path/to/example]!
/// Here is [another one](example:path/to/another one]!

What do you think?

[alice-i-cecile]

Yep, that looks great, assuming the dead intradoc links lint triggers correctly.

[GuillaumeGomez]

Coming back to this, this disambiguator syntax @ would work too and would be coherent with the rest:

/// Oh what a nice [example][example@example_name]!

[GuillaumeGomez]

Opened the PR to add this feature: #132792