documentation: meaning of `mut` in identifier patterns is not documented

[mheiber]

I expected to see this happen: documentation for what mut means in let mut x = 3 and fn foo(mut x: i32)

Instead, this happened:

As far as I can tell, the meaning of mut in identifier patterns is not documented in the Book or the Reference.

The syntax is well-documented in the reference: https://doc.rust-lang.org/stable/reference/patterns.html#identifier-pattern, but not the meaning.

An early chapter of the Rust book gives some examples and contrasts let mut with let but doesn't define mut.

In particular, afaict, neither resource says that upgrading a let to a let mut is allowed, but upgrading a & to an &mut is not generally allowed.

let foo = ...
let mut foo = foo // OK

let bar: &B = ...
let bar: &mut B = &mut*bar // Error

Impact

Experienced users can still get tripped up by things like: https://stackoverflow.com/questions/69845063/why-does-a-level-of-indirection-allow-omitting-mut (I'm a Rust n00b, but posted the question for a Rust-experienced colleague).

How to fix:

If someone has a definition of mut handy, I can make PRs to update relevant parts of the docs. Apologies if mut is already defined and I missed it.

[hkratz]

It is documented here: https://doc.rust-lang.org/stable/reference/variables.html

[mheiber]

https://doc.rust-lang.org/stable/reference/variables.html

Thanks for this reference. The docs you linked to say that "mut" is short for "immutable", but don't define mut or explain what is happening in the code sample above or https://stackoverflow.com/questions/69845063/why-does-a-level-of-indirection-allow-omitting-mut. I would make a PR to the docs instead of an issue, but I'm not confident enough that I can define mut.

[ehuss]

I think the book does try to describe it:

In addition to allowing this value to change, mut conveys intent to future readers of the code by indicating that other parts of the code will be changing this variable’s value.

So, in short, it allows the binding to change.

If you don't mind, can you move this issue over to https://github.com/rust-lang/reference/issues? I agree that the reference is lacking in this regard.

As for your second example regarding &mut, that's a different beast. Although it shares the same token mut, that scenario relates to the borrow checker, which for the most part is undocumented (at least in a formal sense).