rustdoc doesn't substitute type parameters

Opened by Alex Crichton at 2024-11-06 02:02:23

This comes up when you're looking at something like an instantiation of a generic trait. For example, the CharOffsets structure implements Iterator<(uint, char)>, but lots of the default methods refer to an A type parameter, where in this case A = (uint, char).

http://static.rust-lang.org/doc/master/core/str/struct.CharOffsets.html

I'm not sure if we want to go all-out and to type substitution everywhere, perhaps it's good enough as-is?

If we don't substitute, it would probably be good to mention what A is somewhere.
Huon Wilson at 2014-05-09 23:43:31
<del>It could be nice to do something like:</del>
```
U: Iterator&lt;<abbr title="(uint, char)">A</abbr>&gt;
```
<del>with some styling to hint that this is an abbreviation that can be expanded (most browsers show the title attribute as a tooltip).</del>
Tom Jakubowski at 2014-06-23 04:30:33
To clarify, the problem occurs when a type implements a generic trait but does not override a default method using one of the trait's type variables or Self. For example, some type implementing FromPrimitive which does not override its provided methods:
```
pub struct Foo;
impl FromPrimitive for Foo {
    fn from_i64(_: i64) -> Option<Foo> { None }
    fn from_u64(_: u64) -> Option<Foo> { None}
}
```
Will have methods in the impl that look like fn from_i8(n: i8) -> Option<Self>, where Self should clearly be substituted.
Tom Jakubowski at 2014-12-26 21:44:42

Did this get fixed? I tried to update @tomjakubowski 's example, since FromPrimitive is gone:

pub struct Foo;

pub trait Test: Sized {
    fn from_i64(_: i64) -> Option<Self>;
    fn from_u64(_: u64) -> Option<Self>;
}

impl Test for Foo {
    fn from_i64(_: i64) -> Option<Foo> { None }
    fn from_u64(_: u64) -> Option<Foo> { None}
}

and it looks like this:

2015-12-31-134827_389x300_scrot

Steve Klabnik at 2015-12-31 18:48:30

No I think this is still an issue, e.g. http://doc.rust-lang.org/nightly/std/str/struct.Lines.html doesn't substitute Self::Item anywhere
Alex Crichton at 2016-01-11 18:40:49
No, my example from #15977 still holds.
Mathijs van de Nes at 2016-01-11 18:56:58
For lifetimes this can be really misleading, as in this example:
<img width="991" alt="lifetime_bug" src="https://cloud.githubusercontent.com/assets/4452260/19212277/8a8708f4-8d99-11e6-9fd9-98b5ac96b991.png">
This makes it look like get_ref() returns a reference with lifetime 'a, but actually it returns a reference with the longer lifetime 'b.
```
#![crate_type = "lib"]

pub trait Foo<'a> where Self: Sized {
    fn supply_ref(self) -> &'a u32;

    fn get_ref(self) -> &'a u32 {
        self.supply_ref()
    }
}

pub struct Wrapper<'a> {
    val: &'a u32
}

impl <'a, 'b: 'a> Foo<'b> for &'a Wrapper<'b> {
    fn supply_ref(self) -> &'b u32 {
        &self.val
    }
}
```
Michael Sproul at 2016-10-08 09:57:20
Triage: no change
Steve Klabnik at 2019-12-25 16:20:07
As simple as it gets (generic trait, provided associated item):
```
pub trait Trait<T> {
    fn method(_: T) {}
}

pub struct Type;

impl Trait<i32> for Type {}
```
<Type as Trait>::method gets rendered as fn method(_: T) on Type's page instead of fn method(_: i32) which is clearly a bug.

Tho it's hard to tell without looking at the source if it's an instance of the originally reported issue.

This extends to all three kinds (lifetime, type, constant) rendering provided associated items with identity substitutions. E.g., in:
```
pub trait Trait<'a, T, const N: usize> {
    fn method(_: &'a (), _: T, _: [(); N]) {}
}

pub struct Type;

impl Trait<'static, i32, 0> for Type {}
```
León Orell Valerian Liehr at 2024-08-07 23:21:21
triage: no change, you can see this in Chars::nth.
lolbinarycat at 2024-11-06 00:52:25
Ye, I know what the problem is, I just didn't get around to fixing it.
León Orell Valerian Liehr at 2024-11-06 01:21:20
no worries! just doing bulk triage of old rustdoc issues.
lolbinarycat at 2024-11-06 02:02:23