Document how tokens are compared in declarative macros

[bal-e]

I wondered whether something like this would compile:

macro_rules! foo {
    ( r###"hello"### ) => {}; // 3 #-es
}

foo!( r##"hello"## ); // 2 #-es

It appears it does not, but this is not documented on the reference chapter about Macros By Example. There should be a section explaining the exact rules by which tokens are compared; there may be existing code out there that relies on behavior like this. Other examples I can think of:

• Doc comment tokens in matchers are currently ignored.
• Raw idents do not match non-raw idents (and vice versa).
• Suffixed literals do not match unsuffixed literals (and vice versa).

[petrochenkov]

The first item falls under "unfortunate backward compatibility case", and the last two reflect the fact that the matching works at token level, rather than at any "semantic" level.

[bal-e]

Indeed. Maybe there should be a clarification of what "token level" vs "semantic level" entails. Even though I have worked on the underlying code, I found it surprising that the number of #-es affects matching. I imagine end users will be even more surprised.