Annotations (changes and documentation)

[jakhog]

Automatic documentation of platform annotations has been discussed a few times already (#187 and #34), and although a proposed solution is currently available in Documentrospection, it is not used or maintained.

Further, many platform annotations that we use, are more flags than they are values. But the current grammar says that annotations have to be '@' ANNOTATION_ID (STRING_LIT|EXTERN). So we usually end up doing either e.g. @sync_send "" or @sync_send "true". This is slightly annoying.

I propose two solutions:

Solution 1 - Documentation

We could link the AnnotatedElementHelper more closely to the Compilers or the Contexts, and enforce that the compiler registers what annotations it uses, together with a short string explaining the usage and possibly the elements where it can be applied.

What I'm thinking, is that in a Compiler constructor, we do something like:

ctx.registerAnnotation("sync_send", "Send messages by calling functions instead of using the FIFO", "message");
ctx.registerAnnotation("fork_thread", "Call this function in a new Thread", "function");

Then we switch the AnnotatedElementHelper calls to something like

ctx.hasAnnotation(element, "sync_send");
ctx.hasAnnotation(element, "sync_send", "true");
ctx.getAnnotation(element, "sync_send");

And if you try to get an annotation you haven't defined, we print a warning, and possibly don't return anything from those methods, so that we are sure that we properly declare everything.

If we go with this approach, it would be really easy to programmatically generate a list of the currently supported annotations, and their usage, by simply looping through all compilers (and protocols), and printing the results. So that you could use the compiler.registry cli or a new button in Eclipse to get that list.

Solution 2 - Flag annotations

This one is a bit simpler (and slightly unrelated). I propose that we make the string literal following the annotation id optional. So that we can use them as flags as well.

I don't think this would cause any parser conflicts, as I don't think there is any way of declaring an annotation just before any other string literal.

Solution 2 - Done!

[jakhog]

Also somewhat related to #214

[brice-morin]

Note that we might use an EClass instead of the string to give the scope of annotations. Something like ThingMLPackage.eINSTANCE.getThing(), which might give us some more control, and also avoid typos, etc.

[brice-morin]

Note we might also declare optional default values for the annotations (which we typically use in the getOrElse)