Add annotations to CIF (implementation issue)

Now that the design of annotation has been decided in #463 (closed), it is time to start implementing them.

Phase 1

Steps to support annotations fully, on just input variables, as a first phase:

• Add meta-model classes for them. ( !604 (merged))
• Add containments for these new classes for a first concept:
  • Technically for all Declarations, but only InputVariable is supported for now. ( !638 (merged))
• Add @ to the scanner (or @<name> ?). ( !640 (merged))
• Add rules to the parser for the syntax. ( !640 (merged))
• Add annotations to the first concept in the syntax where we also have them in the metamodel.
  • Input variables. ( !640 (merged))
• Add code to the parser and likely to some AST classes to handle the additions, to parse. ( !640 (merged))
• Add extension point for contributing annotation providers. ( !644 (merged))
• Add type checker code to turn parsed annotations into metamodel instances:
  • Type checking them a bit for the generic parts. ( !643 (merged))
  • Using annotation providers for more specific type checking. ( !644 (merged))
  • Type checking for annotations of input variables. ( !643 (merged))
• See the CIF developer documentation for other steps for language changes. Most importantly is probably the adaptation of all tools, like CIF to CIF transformations.
  • Update all common methods, CIF to CIF transformations, CIF tools, and other CIF code for the addition of annotations in general. (nothing is needed)
  • Update all common methods, CIF to CIF transformations, CIF tools, and other CIF code for the addition of annotations to input variables. ( !650 (merged)) ( !678 (merged))
• Add doc annotation. ( !651 (merged))
• Document annotations in the CIF language tutorial. ( !655 (merged))
• Document annotations in the CIF reference manual. ( !667 (merged))
• Document for each tool in the CIF toolset what annotations it supports. (!679 (merged))

Annotations to consider (phase 1)

As for concrete annotations to consider for phase 1, it would be good to have at one concrete annotation, being defined, type checked, documented in the documentation, used in at least one tool:

• My proposal is to add a doc annotation. It seems useful for code generation. For now, the CIF code generator may put the documentation in the generated code.
• Alternatives:
  • A state annotation may be useful for the result of the state space generator. Downside is that it is generated, but no tool processes it as input. (#687 (closed))
  • A plc:input annotation is likely useful for PLC code generation, for input variables.
  • A plc:output annotation is likely useful for PLC code generation, for discrete variables, algebraic variables, and locations (single bit output from 2-location automata).

We went with the doc annotation.

Phase 2

As a second phase, allow annotations on more objects, following these steps, per language concept (type of object) that gets annotation support:

• Allow in syntax.
• Allow in metamodel.
• Add type checking.
• Update all other code (common methods, CIF to CIF transformations, other CIF tools, etc).
• Update the documentation (language tutorial, reference manual, tool documentation, etc).

As for where to allow annotations, I propose to support in the end all of the following, and at least all named elements (elements that must or can have a name):

• On all components.
  • Groups (that are not the top-level specification). (!873 (merged))
  • Automata. (!872 (merged))
  • Group and automaton definitions. (!880 (merged))
  • Group and automaton instantiations. (!880 (merged))
  • Specifications. For now, there is no place to put them in the textual syntax. May need to invent syntax for that, like double @ sign or so. (!853 (merged))
• On all declarations.
  • Algebraic variables. (!821 (merged))
  • Constants. (!831 (merged))
  • Events. (!848 (merged))
  • Continuous variables. (!813 (merged))
  • Functions (including their parameters and local variables). (!867 (merged))
  • Enumerations and enumeration literals. (!864 (merged))
  • Type declarations. (!862 (merged))
  • Input variables. (phase 1)
  • Discrete variables. (!756 (merged))
• On parameters of component definitions.
  • On algebraic parameters (which are essentially placeholders for algebraic variables). (!892 (merged))
  • For component parameters, location parameters and event parameters, the parameters are placeholders, that get replaced by other objects when instantiated. They thus don't exist anymore after component definition/instantiation is eliminated. Hence, annotation providers don't see them. They thus won't get annotations. This differs from algebraic parameters, which become algebraic variables, and for which an expression is given as argument for the instantiation, rather than a reference to an existing object.
• On locations and edges.
  • Locations. (!695 (merged))
  • Edges. (!899 (merged))
• On invariants. (!877 (merged))
• Check what other elements exist that can have a name, but do not yet support annotations.

Phase 3

• Allow @doc("some documentation") as shorter form for @doc($text = "some documentation"). (#801 (closed))
• Allow multiple the same annotations on a single object. (#692 (closed))
• Remove annotations as preprocessing for various CIF tools (#736 (closed))
• Some CIF tools do annotation post-checking on specifications with component definitions/instantiations (#853 (closed))
• CIF annotation type check and pretty printing sometimes uses wrong scoping (#824 (closed))
• All tools that produce CIF models with manipulated/moved/copied/etc annotations should check the constraints on annotations again, to ensure they produce valid output models. (#823 (closed))

Next steps (Phase 4)

Now that annotations have been implemented, this issue has been closed. What remains is to declare annotations a stable language feature, see #869 (closed).