Thanks, I've given some thought on how to address this but haven't come to a real conclusion yet. It would be nice if there was a way to document macros with some kind of pseudo-function syntax, but then with macros you can express things which just aren't available in normal functions. println! is a good example because it basically exists to work around the fact that Rust doesn't have variadic functions (thank $diety) but then you'd have to express it with a signature that doesn't exist in the language. Or even more fundamentally, println! exists in two forms, one of which takes no arguments (and just prints a newline) and one which takes a format string and arguments. That's not easy to express in a single signature. I suppose it could all be written as prose like I've just done here.

I don't think any amount of docs could make the Rust macro syntax palatable. The problem is more fundamental, macros as they are currently implemented are a huge pain to write, even if you know what you're doing. Having to rely so much on recursion for instance adds a lot of complexity.

But on the other hand it means that people are less inclined to abuse them and they're a lot more hygienic than C-style macros...

> Having to rely so much on recursion for instance adds a lot of complexity.

I’ve written some fairly heavy Rust macro code, and I almost never need recursion— the repetition primitives generally prove sufficient for my needs. What are you doing that needs all the recursion?