std docs: strange notation in std::pin docs

[ehuss]

The std::pin module uses strange [mut] notation. For example, Pin<&[mut] Self>). I cannot discern what it is trying to say. I think it should probably not use the brackets, or explain what the syntax means?

[Centril]

It is trying to say &Self / &mut Self. IOW mut?

[steveklabnik]

We should be more explicit then, nowhere else in the docs uses this notation.

…

On Apr 9, 2019, at 7:01 PM, Mazdak Farrokhzad ***@***.***> wrote: It is trying to say &Self / &mut Self. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[czipperz]

It is used in other places inside rustc. The syntax makes sense to me personally.

File: src/librustc/mir/mod.rs
622:50:    /// Some((None, ..)) in the case of and `let [mut] x = ...` because
File: src/librustc_mir/transform/add_retag.rs
174:61:                    // to update tags.  This includes `x = &[mut] ...` and hence
File: src/librustc_mir/borrow_check/move_errors.rs
127:56:                    // opt_match_place is None for let [mut] x = ... statements,
File: src/libcore/pin.rs
163:71://! in your type (for example by implementing some operation on `Pin<&[mut] Self>`)
176:37://! an operation with type `fn(Pin<&[mut] Struct>) -> Pin<&[mut] Field>`?
178:42://! have an operation with type `fn(Pin<&[mut] Wrapper<T>>) -> Pin<&[mut] T>`?
182:59://! After all, the pinning projection lets us get a `Pin<&[mut] Field>`.

[czipperz]

I'm going to open a pr for this...