Plans for reference manual

[stefanos82]

The documentation we currently have is, as its title says, an overview; it does not describe the entire language.

For example, I'm looking for an annotation list and cannot find anything in docs.

I have to go to lualib/nelua/typedefs.lua to find what I'm looking for, only to get more confused as there are 3 different types of annotations:

• Function annotations
• Variable annotations
• Type annotations

Why do I say more confused? Because as a user, all I see is the following syntax, e.g. <noinit>, and I expect the same annotation to be supported all 3 aforementioned categories, but that is not the case.

A function in C can be of type static, but in Nelua we have it as a variable annotation and that perplexes things even more.

Does it mean I can't have a function and a variable as of type static, only variables?

[edubart]

The documentation we currently have is, as its title says, an overview; it does not describe the entire language.

True, a section for annotations is lacking, this is in my documentation TODO for the future, I am delaying to improve that after I implement the planned feature of custom annotations.

Why do I say more confused? Because as a user, all I see is the following syntax, e.g. <noinit>, and I expect the same annotation to be supported all 3 aforementioned categories, but that is not the case.

It does not make sense for each annotation to work on all categories, because an annotation always depends on its use context, but you should always get compile errors when using an annotation in the wrong context.

A function in C can be of type static, but in Nelua we have it as a variable annotation and that perplexes things even more.

This is more a C problem, because in C static have slightly different meanings when using for functions or variables. The <static> annotation is there just to expose this C feature, but I don't recommend using it, avoid it if you can, you may only want to use it in case you really intend to change the C codegen to make a variable with static lifetime in the middle of a function. In Lua style you usually make a variable with static lifetime by declaring it in the top scope, and I recommend doing this instead of using <static> annotation.

Does it mean I can't have a function and a variable as of type static, only variables?

All functions are already made static in C by default, so there is no need for the <static> annotation for functions, but this is not the case for variables, while all variables in the top scope are made static, the variables declared inside function scopes are non-static, but you can force them to be static with the <static> annotation.

I have to go to lualib/nelua/typedefs.lua to find what I'm looking for, only to get more confused

Just because an annotation is there, it does not mean you should use it or understand it, some annotations are available just to expose some C features, so the language doesn't block or hide some C features, but some are questionable to use, like:

• <static>, because you can declare in top scope instead
• <aligned> and <packed>, because this is no standard C and may not work on all compilers
• <atomic> and <threadlocal>, because requires a C11 compiler