Rust: Rustdoc: replace Self with concrete types

[stjepang]

It's pretty common to write code like:

pub struct Foo {
    field: usize,
}

impl Foo {
    pub fn new() -> Self {
        Self { field: 0 }
    }
}

impl Default for Foo {
    fn default() -> Self {
        Self::new()
    }
}

Generated docs:

This is a simple example, but generally I find documentation much easier to browse when Self is replaced with concrete types (i.e. Foo). Because of that, I tend to write concrete types in public interfaces, but otherwise use Self everywhere else because it's so easy to type.

It'd be great if rustdoc could automatically replace all occurences of Self in the interface with concrete types.

cc @jeehoonkang

[Centril]

I disagree. If Self is a complex type, then keeping -> Self is easier to read than comparing the complex type -> ComplexType to ensure that it's equivalent to the type in the impl Trait for ComplexType header.

Displaying -> Self is a good cue that the user only needs to check the header.

[GuillaumeGomez]

I agree with @Centril.

[alercah]

How about having it so that if you hover (or click?) on Self, it expands to show the full type? That way it's clear which is Self, but also allows seeing the full type in context? This would be especially helpful for associated types, I imagine.

[Centril]

@alercah If the overhead (consider crates such as winapi, cc @retep998) isn't too large, I can totally live with that.

[GuillaumeGomez]

@alercah: Sounds like a good idea actually.

[QuietMisdreavus]

It's worth noting that -> Self in non-trait impl blocks is determined by the impl block. I've wanted to streamline docs pages and remove these impl headers, since they can hide information by separating it from the methods where it applies. Making sure this Self type is visible would help greatly in this situation.

[retep998]

@Centril The cost of documenting winapi is 90% syscalls from creating hundreds of thousands of files. As long as solving this issue doesn't involve creating more files, then the cost will be negligible.

[pickfire]

Another solution would be to link to impl https://github.com/rust-lang/rust/issues/76670 like @alercah mentioned. I don't think doing some magic with Self is the way to go since it is too complex. Should we still keep this issue open?