Document the Annotation feature

[BruceEckel]

I was unable to find information about this; it just seemed to start showing up.

For example:

• Are annotations only provided by the language or can you define your own
• Do annotations take arguments
• etc.

[magnus-madsen]

For now, annotations and their meaning is defined by the language.

The hope is to avoid that programmers define 17,000 different @NotNull annotations, and also that programmers would want to reflect on them.

So annotations only serve some well-defined purpose that is part of the language.

Note in some cases we use keywords instead of annotations. E.g. there is no @Override annotation, instead we use the keyword redef.

[BruceEckel]

Reasonable enough. Python is probably a good test case to see whether user-programmable annotations (decorators in Python) produce too much noise (not that I have seen), but I don't know enough about Flix yet to know whether that would be beneficial.

A brief section in the docs that say what they are, what they do, that you can't make them yourself and also, importantly, the list of annotations would be helpful for future adopters, I think.