Improve documentation for generated functions

[GlenHertz]

(I couldn't find another open issue.)

I was reading the docs trying to understand when and how to use @generated functions but there is just an example without much explanation. In one of Stephan's presentations he talked about generated functions but only had time to quickly show what it does. As a feature that allows you to write multi-dimensional code I think this is one of the top features of 0.4 and should cover things like: how it interacts with the compiler/parser, how to debug/code with them, performance implications, etc.

[yuyichao]

Have you seen http://julia.readthedocs.org/en/latest/manual/metaprogramming/#generated-functions ?

[yuyichao]

And I think it include what you want already.

how it interacts with the compiler/parser

It let you generate code with type information but when and how many times it is called is undefined.

how to debug/code with them

You can print out the AST and otherwise use/debug them as usual functions.

performance implications, etc.

No difference from normal functions.

[GlenHertz]

No, I didn't find that, thanks. I tried searching the HTML docs for @generated but that doesn't work. I then tried generated function but it doesn't find the obvious section.

The docs are really good except it starts using interpolation inside expressions like :(I[$N] - 1) without saying what $N does. I'm not sure if this was added by mistake or not. Perhaps the first two examples need to use :($x^2)? I find these things confusing and was hoping that #10940 would help make meta-programming easier but it was never merged.

[timholy]

The docs are really good except it starts using interpolation inside expressions like :(I[$N] - 1) without saying what $N does.

It's assumed you've read the material higher up on the same page 😄.

[tkelman]

Whenever the JuliaCon videos finally go up, you'll probably want to watch @jakebolewski's talk. He changed subjects so the title on the program isn't accurate, he spoke about generated functions in some detail.

[ihnorton]

Link to talk: https://www.youtube.com/watch?v=KAN8zbM659o&list=PLP8iPy9hna6Sdx4soiGrSefrmOPdUWixM&index=55

Closing this for now as the metaprogramming section does need to be read in full. Doc improvement PRs are always welcome.