Document destructuring assignment

[varkor]

Adds documentation for the destructuring_assignment feature (rust-lang/rust#71126), which is accepted for stabilisation (rust-lang/rust#90521). The documentation is based on the RFC text.

[ehuss]

TYVM for the PR!

[ehuss]

I'm a bit confused about the interaction of the underscore expression and macro_rules. The following doesn't seem to work for me:

#![feature(destructuring_assignment)]

macro_rules! expr {
    ($e:expr) => {};
}

fn f() {
    expr!(_);
}

Is there some uniqueness about the underscore expression that prevents it from being used directly as an expr fragment? It seems to work OK if inside some other expression (like expr!((_));). If this is intended, then I think a footnote or something should be added to the metavariables section.

[petrochenkov]

I'm a bit confused about the interaction of the underscore expression and macro_rules

It's all due to backward compatibility, for example _ is also a (keyword) identifier, but it doesn't match ident in macro_rules.
Every time we add something to Rust grammar proper we have to add exceptions to macro_rules matchers due to compatibility (unless the case is obscure and no breakage is found by crater).
cc rust-lang/lang-team#111

[varkor]

destructuring_assignment has now been stabilised (rust-lang/rust#90521), so I will update this issue soon with the requested changes.

[varkor]

I've updated the pull request with the requested changes.

[ehuss]

ping @varkor Just checking in to see if you had any questions, and if you can resolve the conflicts and address the final review comment.

[varkor]

@ehuss: thanks, I will do soon. I've just been in the process of moving recently, so I've been a little distracted. Will try to respond to the comments before the end of next week :)

[varkor]

I've addressed the final comment and fixed the merge conflict.

[ehuss]

Looks great, thank you very much!