What I'd really like in the org-mode doc somewhere (or on worg?) is the babel syntax broken out like a traditional programming language, by which I mean describe the syntax[es] for *defining* a function in one place (including all the ways to define args and their default values), and describe the syntax[es] for *calling* a function in a separate section (including how to pass args). If the variable semantics vary by language (as they do), just say so (e.g. when defining a SQL function, vars are substituted into the body by prefixing the names with $, but in python they are local vars in non-session mode and global vars in session mode and so on. Maybe this doc section shouldn't try to enumerate all those languages, but just redirect to the proper worg babel language page for details on arg handling.
I think all this info is already there in one place or another, but IMHO it's not organized in such a way that a newbie can start to use org-mode as a metaprogramming language without lots of false starts and reading the source (like I did).