And there was a time where people thought Hungarian Notation was a great idea until they realized that it became an impediment to necessary change.
I was just grateful that the documentation is quite up front about when something is a macro.
I’m talking about (macro) to the right - in front of the link </> to the source - I always quickly scan over there to know what I’m dealing with.
The problem is not confusing functions with macros. The problem is confusing macros (and theoretically functions) with special forms
The syntax reference seems almost perfect. I’d add a list of keywords that create blocks (do, else, etc) because I can’t find those documented in official sources.
Yes, and no!
Some of the pages you reference, operators, guards and unicode syntax, would fit in what I would call a language reference. The syntax reference, however, would not. It is mainly a description of the AST and only indirectly a language reference. While it is interesting if I want to write macros or write my own source transformations the AST is uninteresting to those who want to learn the syntax and it clutters up the text. So definitely keep it but not as part of a language reference.
Re the discussion of macros. For a language reference knowing whether something is a macro is actually not very interesting. At most all you would need is a tag saying whether it is a special form or a macro. What confuses the matter is alternate forms for do ... end (which unless you haven’t already guessed it I think is bad idea 
) but you could just describe both alternatives without going deeply into why.
Agree. For the tiny benefit of writing some one-liners, you get 2 ways of doing the same thing. It confuses newcomers and makes code written by different people often times inconsistent.
IIRC it is not for any “benefit”. It is a consequence/side effect of own the parser and the AST works.
But it was not “added” for one liner. I may be wrong or badly remember.
Since we’re bikeshedding about syntax, I actually prefer the keyword list with block contents delimited by parenthesis to do ... end.
The one line form is less verbose and more consistent with the way the function is defined.
Not sure I understand what you mean and it may just be my personal preference but I like to have a very clear understanding/separation between generative, compile time and runtime effects. Preprocessors often aren’t considered “part of the language” and their syntax is typically so different that it’s very clear what has an effect before the code hits the compiler.
In Elixir’s case macros are such an integral part of “the language as it’s employed” that it takes a lot more conscious effort to differentiate “source code” with compile time effects versus runtime effects.
The confusion experienced by newcomers is simply a warning sign that they are approaching Elixir with an ill-fitting mental model. As such that confusion should be exploited as an opportunity to explain in what ways Elixir is different from other languages.
So while superficially def looks like a keyword from Ruby or Python the moment they look at the documentation (which I think isn’t a completely unreasonable expectation) alarm bells should go off.
def(call, expr // nil) doesn’t look anything like “function definition syntax” - I’d say it looks more like a code generation directive. This is also the perfect opportunity to drive home the fact that imperative languages make heavy use of statements while functional languages tend much more towards expressions.***
Once newcomer’s have sorted out that difference, they’ll comfortably fall back to treating def ... do ... end just like a “definition” while not being confused by def ... , do: ... and they’ll also be better prepared to deal with any other misunderstandings that they are bound to discover in their journey ahead.
*** I find it discouraging how often Elixir/Erlang educational material uses the term “statement” when “expression” is correct. For example, there is no case statement, only a case expression - if you choose to ignore the returned value then that is your own business.
I felt like this when I read the syntax section too. It’s not that it isn’t good information or isn’t relevant overall. It’s just that when I read it I kept thinking, “This is a very good overview of how the parser works, but how will this help from getting a compile time syntax error?”
Honestly, everything I would expect in a Syntax section is basically just a collection of summaries about important things to the language. Then each thing easily links to the relevant section that has the rest of the information.
e.g.
Kernel module is imported automaticallyimport/2 allows one to easily access functions or macros from others modules without using the qualified namedefmodule is used to declare new modulesdef is used to declare new named functions and can only be used with defmodulelist of codepoints. A series of double quoted characters is a binary.Basically all things that could provide a quick refresher or if I am trying to debug some Elixir code and have never really messed with the language.