Allow CIF @doc annotation with nameless arguments
Currently, the name is mandatory, meaning we must write @doc($text = "some documentation")
rather than @doc("some documentation")
. We want to make the latter possible.
The idea is that all arguments can be nameless, all named, or a mix of it. It is up to the specific annotations to decide what makes sense. For the @doc
annotation, it will require on or more arguments, without names. The names are simply not needed anymore. Also, it can then have multiple arguments, which allows to more easily write multiline documentation. That is:
@doc(
"Some first line.",
"Some second line.",
)
would be allowed, and is the same as:
@doc("Some first line.\nSome second line.")
Ideally, we just additionally allow an Expression
for AnnotationArg
in addition to @IDENTIFIERTK EQTK Expression
and @RELATIVENAMETK EQTK Expression
. However, then a = b
can be parsed in two ways, as an Expression
, or as @IDENTIFIERTK EQTK Expression
. The parser thus has conflicts and can't be generated then. We thus need to replace =
by something else. This is a backwards incompatible syntax change for models with annotations. We considered multiple different symbols instead of =
. ->
is longer, which is not that nice. :=
suggests imperative assignments with old and new values, which is not a good fit for declarative annotation arguments. We arrived at :
, which is also already used for dictionary key/value separation.
Tasks:
- Change syntax of
=
to:
. - Allow also
Expression
for arguments. - Change the
@doc
annotation to make use of this.
Since this is a backward incompatible change, we should do it sooner rather than later, to prevent having to change even more documentation, test models, etc.
Addresses #593 (closed)