To avoid syntax duplication (e.g., having to handle doc strings here), let's merge these rules with the parent ones.

For instance, the first rule would become:

macro_rules! derive_alias {
    (
        #[derive($MacroName:ident !)] = #[derive($($derives:tt)*)];
        $($($rest:tt)+)?
    ) => (
        /* current output for `$MacroName` */

        $(
            $crate::derive_alias! { $($rest)+ }
        )?
    );

• also, as a general rule of thumb, nested macro invocation in trailing position are better done using {} rather than ();, just in case the last one expands to as statement expression (e.g., { 42 }), so as to avoid discarding its value (e.g., the 42: i32).

I don't think I understand what you mean here, in two specific cases:

When you say "let's merge these rules with the parent ones", what is "parent" referring to in this context? Is it positional, like "the rule above this one", or more like "the rule that calls this rule", or something else entirely?

The {} vs () comment I'm even less clear on. I'm not quite sure what doesn't click here for me, but I'll lay out what does make sense and with a bit of luck, you might see whatever it is that I'm not seeing. 🤔

I'm reasonably sure of the terms here, understanding Items to be distinct from Statements and Expressions, and in the context of macros, these map to the fragment-specifier bits in the documentation for Metavariables, right? So we're matching those at the macro entry point (matcher, but "matching in the matcher" sounds awkward) and then forwarding that on to another macro in the transcriber section? So the docs on Forwarding a matched fragment have this bit that seems relevant:

When forwarding a matched fragment to another macro-by-example, matchers in the second macro will see an opaque AST of the fragment type. The second macro can’t use literal tokens to match the fragments in the matcher, only a fragment specifier of the same type. The ident, lifetime, and tt fragment types are an exception, and can be matched by literal tokens.

And I'm somewhat fuzzy on this part, but I think that suggests that if we matched a tt, it could be kind of anything, but if we matched something more specific, like a stmt, item, or expr, it can only be forwarded to something that accepts those. So it's anything until we treat it as something, and from then on it's only that thing. And since we want to match all of these things, we're not being specific, and just matching some number of tt and forwarding them on blindly, right? Which is why we don't know if we have a stmt, item, expr, or something else.

If I've got that right, then I think I understand the context for why the (potential) problem occurs.

But the differences between {} and () still aren't clear to me at this point.

Looking up some references to figure it out led me to this chapter in The Little Book of Rust Macros, which includes this sentence that I think explains the difference?

In fact, function-like macros can be invoked with any kind of parentheses as well, but invocations with { .. } and ( ... );, notice the trailing semicolon, are special in that their expansion will always be parsed as an item.

My brain parses that as { .. } and ( ... ); always parse as an item, but [ ... ] could be something else (like a stmt or expr?).

Which seems wrong, because you're suggesting a change between two types of parentheses that I (likely incorrectly) think do the same thing?

So... yeah. I'd like to understand this, I've read the docs (not exhaustively), heck, I've even used this stuff a decent amount, and it (on the surface at least) works the way I expect it to, so I think I'm probably not too far off.

I know that's a wall of text, and I appreciate that it takes time and effort to wade through that. If you happen to notice where my blind spots are, I'd be grateful for the insight, and if I'm misunderstanding something important, I'd welcome any corrections.

Thanks for your patience!

Ditto here (also, whitespace is very important for macro readability, let's avoid squashing things together)