Allow generic parameters in intra doc link

[dtolnay]

pub struct Collection<T> { __: T }

/// [`Collection`], [`Collection<T>`]
pub struct S;

Currently this renders as ` Collection, [Collection<T>] `, where the first link is ok but the second link is not rendered. I think these should both point to struct.Collection.html. For some types it can be clearer to include the type parameters when discussing them.

Mentioning the tracking issue: #43466

[Nemo157]

In relation to the objection @GuillaumeGomez had on the tracking thread, I have a usecase where I want to link to the different parts of a fully applied (nested) generic type.

Extending the example slightly, should the following also work:

pub struct Collection<T> { __: T }

pub struct U;

/// [`Collection`], [`Collection<T>`], [`Collection<U>`]
pub struct S;

and should that result in something like:

Collection, Collection<T>, Collection<U>

?

[nixpulvis]

Would it make sense to support entire specialized doc pages like ".../target/doc/general/struct.General<i32>.html" (exact URL can't look like this I believe) so a link to a specific type of a polymorphic type can filter out all other impls from the docs?

This might be nice in some specific use cases that make heavy use of specialized implementations.

[jyn514]

support entire specialized doc pages

That seems a much bigger change than the one originally suggested. For one thing we'd have to design what the page should look like.

I wonder if we could hack this by deleting all text between < and > in intra-doc links? AFAIK the only time those are valid is for generics, and an unclosed delimiter would be a syntax error in a type.

[jyn514]

I've also seen people trying to use Some(T) which would be nice to support. This one is tricky because Some() is parsed as a function disambiguator. But maybe since we currently don't distinguish between functions and other types just stripping the T would work?

[GuillaumeGomez]

I'm still strongly against it. However, I don't remember if we can mix type and anchor? Like: [Collection#some-impl]. In this case, it'd fix all issues I assume and is far more simple to implement (if not already done).

EDIT: It's already supported. I'll add it to the documentation of intra-doc links.

[jyn514]

Direct link so all the discussion is in one place: #43466 (comment)

[jyn514]

In this case, it'd fix all issues I assume and is far more simple to implement (if not already done).

Well, it's still possible to link to Some directly. But it makes you use [Some(T)](Some) instead of the direct [Some(T)]. So I think we should consider making it easier for the same reason as Option<T>. See #74300 (comment) for an example.

[camelid]

Is a simple version of this planned to be implemented? A nice start would be something where Vec<T> just links to Vec. Then a lot of duplication like this could be avoided:

Here's a link to [`Vec<T>`].

[`Vec<T>`]: Vec

[jyn514]

Mentoring instructions:

Just before calling resolve_with_disambiguator, replace path_str with a version that has everything in <> stripped. Note that this should match the brackets: Vec<Option<T>> should turn into Vec, not Vec>.

[camelid]

I would be interested in implementing this.

@rustbot claim