rustdoc doesn't substitute type parameters

[alexcrichton]

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?

[huonw]

If we don't substitute, it would probably be good to mention what A is somewhere.

[tomjakubowski]

It could be nice to do something like:

U: Iterator&lt;<abbr title="(uint, char)">A</abbr>&gt;

with some styling to hint that this is an abbreviation that can be expanded (most browsers show the title attribute as a tooltip).

[tomjakubowski]

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.

[steveklabnik]

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:

[alexcrichton]

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

[mvdnes]

No, my example from #15977 still holds.

[michaelsproul]

For lifetimes this can be really misleading, as in this example:

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
    }
}

[steveklabnik]

Triage: no change

[fmease]

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 {}