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