Add annotations to CIF (implementation issue)
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 Declaration
s, but onlyInputVariable
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).
- A
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). -
Automata. -
Group and automaton definitions. -
Group and automaton instantiations. -
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). -
Enumerations and enumeration literals. (!864 (merged)) -
Type declarations. (!862 (merged)) -
Input variables. (phase 1) -
Discrete variables. (!756 (merged))
-
-
On algebraic parameters (which are essentially placeholders for algebraic variables). -
On locations and edges. -
Locations. (!695 (merged)) -
Edges.
-
-
On invariants. -
Check what other elements exist that can have a name, but do not yet support annotations.
Phase 3
Potential follow-ups:
-
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) -
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. -
Declare annotations a stable language feature.
Addresses #463 (closed)