Add documentation for meta variable expressions

[c410-f3r]

Requested in https://github.com/rust-lang/rust/pull/122808

[ehuss]

@c410-f3r Can you update this from the changes in https://github.com/rust-lang/rust/pull/124987?

[c410-f3r]

Updated

[traviscross]

@c410-f3r: We looked at this in the rustdocs call today. Do you have any thoughts on the feedback given above? If so, that could help us in reviewing this.

[c410-f3r]

Feedback looks good but I personally prefer to wait for the decision about https://github.com/rust-lang/rust/pull/122808#issuecomment-2156454878.

Otherwise this could be my third reverted PR. See https://github.com/rust-lang/reference/pull/1179, https://github.com/rust-lang/reference/pull/1251, https://github.com/rust-lang/reference/pull/1192 and https://github.com/rust-lang/rust/pull/99435.

[RalfJung]

Feedback looks good but I personally prefer to wait for the decision about https://github.com/rust-lang/rust/pull/122808#issuecomment-2156454878.

The problem is that currently we are guessing what the proposed semantics even are. So someone who knows the implementation needs to write up-to-date information on that before a decision can be made. Some of the feedback in this PR is of the form "we still don't know what the semantics are, please clarify".

This is why we generally require a reference PR before t-lang can make a final stabilization decision: they need to know what is even proposed for stabilization!

[c410-f3r]

I will try to address all questions this weekend in my free time.

For what it is worth, here goes another illustrative example in the meanwhile.

#![feature(macro_metavar_expr)]

macro_rules! no_repetition {
    ( $( [ $( ( $($i:ident)* ) )* ] )* ) => {
        (
            // ****** 1 `ident` count *****
            //
            // Guided by 6 innermost `ident` from `$($i:ident)*`
            //
            // 6 (a b c d e f)
            [${count($i)}],

            // ****** 1 `ident` count *****
            //
            // Guided by 5 middle `(...)` from `$( ( $($i:ident)* ) )*`
            //
            // 5 (() () () () ())
            [${count($i, 1)}],

            // ****** 1 `ident` count *****
            //
            // Guided by 3 outermost `[...]` from `$( [ $( ( $($i:ident)* ) )* ] )*`
            //
            // 3 ([] [] [])
            [${count($i, 2)}],
        )
    }
}

macro_rules! one_repetition {
    ( $( [ $( ( $($i:ident)* ) )* ] )* ) => {
        (
            // ****** 3 `[...]` counts *****
            //
            // Guided by 6 innermost `ident` from `$($i:ident)*`
            //
            // 2 (a b)
            // 4 (c d e f)
            // 0
            [$( ${count($i)}, )*],

            // ****** 3 `[...]` counts *****
            //
            // Guided by 5 middle `(...)` from `$( ( $($i:ident)* ) )*`
            //
            // 2 (() ())
            // 3 (() () ())
            // 0
            [$( ${count($i, 1)}, )*],
        )
    }
}

macro_rules! two_repetitions {
    ( $( [ $( ( $($i:ident)* ) )* ] )* ) => {
        (
            // ****** 5 `(...)` counts *****
            //
            // Guided by 6 innermost `ident` from `$($i:ident)*`
            //
            // 2 (a b)
            // 0
            // 1 (c)
            // 0
            // 3 (d e f)
            [$( $( ${count($i)}, )* )*],
        )
    }
}

fn main() {
    let (innermost, middle, outermost) = no_repetition!([(a b) ()] [(c) () (d e f)] []);
    assert_eq!(innermost, [6]);
    assert_eq!(middle, [5]);
    assert_eq!(outermost, [3]);

    let (innermost, middle) = one_repetition!([(a b) ()] [(c) () (d e f)] []);
    assert_eq!(innermost, [2, 4, 0]);
    assert_eq!(middle, [2, 3, 0]);

    let (innermost,) = two_repetitions!([(a b) ()] [(c) () (d e f)] []);
    assert_eq!(innermost, [2, 0, 1, 0, 3]);
}

[rustbot]

:umbrella: The latest upstream changes (possibly f80986bb34aa67f30bbb6b92f7b69b250e275126) made this pull request unmergeable. Please resolve the merge conflicts.