Also for learning purposes I started writing a quick reference for syntax and stuff I find useful.
rkma
Onor.io
Robert are you looking for something in BNF? Or would that be too low level for your purposes?
1
brentjanderson
rvirding
Creator of Erlang
I think you need a reference manual for the language. Now most of what most people (me anyway 
) would consider language constructs are described in Kernel and Kernel.SpecialForms as if they are function/macro calls, not as language constructs. I know that this is what they really are, and that sometimes this is important, but for describing “the language” this does not make sense. Yes, there are tutorials and books that are good but somewhere I need a reference of the language, or at least what I perceive as being “the language”.
The Erlang reference manual is not too bad in this respect. It is not a formal language description but it systematically goes through all the language constructs. I can find each construct, or group of constructs, and see what they should look like and what they do. For example I can see all the arithmetic operators grouped together with a simple description of what each does. I can also see the relative priorities. You can also link into the module documentation when necessary.
I think being able to group constructs is a useful thing with a reference manual. For example I could see everything about defining macros in one place and get better feeling for how they work together. Or everything about modules in one place.
Another problem with Kernel and Kernel.SpecialForms is that they differentiate between functions and macros which is generally not that interesting for users. It is correct and relevant when describing these modules but not when describing the language. For me the user it is not interesting that case is a macro.
I think the difference between a tutorial/book and a reference manual is that the reference manual is a more structured description while the tutorial/book are often more example driven. You need both but for different things.
I hope this wasn’t too garbled.
6
michalmuskala
Only things in Kernel.SpecialForms are the things handled by the compiler. The Kernel module is implemented in Elixir itself. This makes it in some ways hard to differentiate between language constructs and syntax extensions built using macros. Should whole Kernel module be considered language constructs?
I think it might be useful to have a grouped “index” of sort in the Kernel module docs, similar to what we do for Ecto.Query.API. It gives a nice overview with links to the particular documentation of each macro.
About the macro/function distinction in documentation, I saw a proposal to change ex_doc to get rid of it and have it all together.
1
tmbb
In my opinion no. I’m with @rvirding. A proper reference of the language is important. This is something Python does well: even though python is an ungodly mess of runtime metaprogramming, the syntax is simple and explained in the language guide. The same guide also teaches you to de.sugar things until you hit the very basics
I’m starting to get comfortable with elixir (enough to build web apps, genservers, mix tasks, etc.), and it is becoming a little scary how little I know about what is syntax and what are macros.
1
michalmuskala
In 1.5 the docs gained some new pages (and expanded some of the old ones):
- Syntax reference: Syntax reference – Elixir v1.5.0-rc.0
- Operators: Operators – Elixir v1.5.0-rc.0
- Guards: Guards – Elixir v1.5.0-rc.0
- Unicode syntax: Unicode Syntax – Elixir v1.5.0-rc.0
This forms a large part what I would understand as a “language reference”.
Together with the:
- Special forms documentation: Kernel.SpecialForms – Elixir v1.5.0-rc.0
- Default imported functions: Kernel – Elixir v1.5.0-rc.0
This covers most, if not all, things you’d be facing using Elixir day-to-day.
7
OvermindDL1
As nice as macro’s are being called just like functions that allows easy conversion to/from macro or def implementations, I do kind of wish that macro’s had to be called with, say, a bang on the end, so something!() would be calling a macro named something and something() would be a normal function call similar to how other languages do (consequently I really dislike that bang functions in elixir are used to represent throwing variants, but it is a common style now, blehg, matching should be the causes of such raises or better constructs like smarter piping). It would be easier for newbies as it makes it obvious then what is a call compared to what mutates code (similar to rust for example, bang calls are macro’s there as one example).
0
michalmuskala
That would be tiresome really quickly if you consider how much of elixir is macros - and that’s skipping the defmodule and def - and, or, and not operators are macros. So is the in operator and if expression. This would mean the average of ! in Elixir programs could start to match the number of $ in PHP.
3
