JuliaLang/julia — pull request #6794 by mbauman (2014-05-09 18:28:34+00:00)
Title: Expand macro documentation

These changes are based somewhat on the [discussion on the julia-users list](https://groups.google.com/d/msg/julia-users/YTZM3Biy-rM/m0orpSjQ8RIJ) and somewhat on my own stumbling points as I was learning how macros worked.

Here's the motivation behind these changes:

* Stress that macros *return* an expression to be evaluated, and hopefully make it look like they're less magical to newcomers. Make `return` explicit in the examples, so it looks less like textual substitution and more like a mapping from exprs to an expr.
* Provide an example where the macro is more than just return an expression. The changes to `@assert` since the original documentation was written make this very natural without needing to contrive another example.
* Use function such as `macroexpand` and `dump` in the examples to help make things more concrete and give users tools to play with.
* Make the hygiene section introduction a bit more clear, with an emphasis that the only thing it needs to worry about is the returned expression.

I think this should help folks 'get' macros a bit quicker. I hope.