Replaced self-reflective explicit types with clearer Self or Self::… in stdlib docs

[regexident]

Many docs examples use explicit types instead of the semantically more clear Self/Self::… aliases.

By using the latter it's clear that the value's type depends on either Self, or an associated type of Self, instead of some constant type. It's also more consistent (and I'd argue correct), as the current docs aren't really consistent in this, as can be seen from the diff.

This is a best effort PR, as I was basically going through the docs manually, looking for offending examples. I'm sure I missed a few. Gotta start somewhere.

[rust-highfive]

r? @joshtriplett

(rust_highfive has picked a reviewer for you, use r? to override)

[joshtriplett]

This looks great!

@bors r+

[bors]

📌 Commit 698bbe5 has been approved by joshtriplett

[joshtriplett]

Also, is it just me, or does it seem like in the context of an impl block with a type Output, you should be able to write -> Output instead of -> Self::Output?

[regexident]

Would be nice, but how would one distinguish between associated and scoped types?

struct Foo;
struct Bar;
struct Foobar;

trait Trait {
    type Foo;

    fn foo() -> Self::Foo;
    fn also_foo() -> Foo;
}

// current syntax:
impl Trait for Foobar {
    type Foo = Bar;

    fn foo() -> Self::Foo {
       Bar // everything nice and clear
    }
    fn also_foo() -> Foo {
        Foo
    }
}

// discussed syntax:
impl Trait for Foobar {
    type Foo = Bar;

    fn foo() -> Foo {
        Bar // ☝🏻 Foo is actually Bar 🤷🏻‍♂️
    }
    fn also_foo() -> Foo {
        Foo
    }
}

[joshtriplett]

@regexident Oh, I see. Given that associated types aren't in scope today, putting them in scope would break backward compatibility. :(

(If not for that, you could disambiguate by writing self::, as in "at module scope".)

[regexident]

Swift does things the way you proposed and cannot express the latter without a sacrificial typealias on the outer type (within the outer scope).

Swift also implicitly turns generic arguments into public typealiases of the type. Nice in 90% of situations, super annoying in the remaining 10% (as your argument's name might collide with an associated type of a protocol, which in turn can collide themselves, etc. It's all but hygienic.).