Rustdoc: replace Self with concrete types

9ac6379
Opened by Deleted user at 2020-09-13 13:06:05

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

  1. 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.

    Mazdak Farrokhzad at 2017-11-22 20:47:35

  2. I agree with @Centril.

    Guillaume Gomez at 2017-11-23 19:57:15

  3. 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.

    Alexis Hunt at 2018-02-08 15:45:44

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

    Mazdak Farrokhzad at 2018-02-08 15:48:34

  5. @alercah: Sounds like a good idea actually.

    Guillaume Gomez at 2018-02-08 16:00:12

  6. 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.

    QuietMisdreavus at 2018-02-08 16:14:58

  7. @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.

    Peter Atashian at 2018-02-08 23:02:04

  8. 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?

    Ivan Tham at 2020-09-13 13:06:05