Documentation improvement (?), macro last comma, optional

1

Hi,
Just something that has been tripping me up:

After reading
https://doc.rust-lang.org/reference/macros-by-example.html#repetitions, I may have overlooked it but for this expression:
($($t: expr),*)=>{ it is not written that the last comma is optional.
When one reads it, one could expect the comma to be required, even for the last item in the list.

Instead ($($t: expr,)*)=>{ does require it. Yes a last optional comma in the input can be handled with ($($t: expr),*$(,)?)=>{.

But I think it would be clearer to write that the macro system implicitly lifts the requirement for the last separator. Maybe it's in the doc and I didn't see it. But it should be made clearer.

So we would have here:

In both the matcher and transcriber, repetitions are indicated by placing the tokens to be repeated inside $(…), followed by a repetition operator, optionally with a separator token between.

Note that the compiler lifts the requirement for the last separator: it must not appear in the input. If you need it, put the separator in $(…).

or something of the like; this part need to be clearer.

1 Like
2

I agree this could be more clear. But IMO it's not that any requirement has been "lifted", it's that the actual requirement is:

a separator token between

and a trailing separator is not "between".[1] Perhaps this could be clarified with a new sentence after that quote:

Repetition operators with separator tokens do not permit a trailing separator token on their own, only separators in-between. If you want to permit a trailing separator token, you may do so by using an optional fragment. For example, $( $i:ident ),* $(,)? will permit a trailing comma after the comma-separated idents.

  1. To me "requirement lifted" implies that a trailing separator would still be allowed. ↩︎

1 Like
3

That would be much clearer and certainly avoid many questions!