Expand docs on Peekable::peek_mut

[lukaslueg]

Slightly expand docs on std::iter::Peekable::peek_mut, tracked in #78302

r? @m-ou-se

[m-ou-se]

Thanks!

I think the if let Some(p @ &mut &2) syntax might be a bit too advanced/unknown for a basic example. Maybe a regular if let Some(p) followed by something like an assert_eq!(*p, &2) would be better. What do you think?

[lukaslueg]

I thought about that too and decided on the nested if in the first PR. Now I changed my mind because afaics we are encouraging people to use features which prevent nesting (e.g. match ... Some(n) => { if n > 0 {). The comment, therefore, says "and match on the next value.".

No strong opinion, poke at me and I'll change to an assert, which equally reflects what's going on.

[m-ou-se]

I feel like the original one (the two ifs) was also fine. if and and assert_eq!() would be fine. Or even just .unwrap() would be fine. But I think it's better if we avoid the p @ &mut &2 syntax, as it distracts a bit from what the example is trying to show, since most people will be unfamiliar with it.

[lukaslueg]

agreed

[m-ou-se]

@bors r+ rollup

[bors]

📌 Commit 08ec201 has been approved by m-ou-se