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...