Define more annotations as declarations

[HansOlsson]

More consistent non-syntax variant of defining annotations, based on comments in #2999

Notes:

• A remaining issue is whether they (and experiment) should be parameter, constant, or evaluable. That may be easier to handle in a separate PR.
• DocumentationClass was previously syntactically incorrect as grammar.
• It is consistently using mathit for the message to replace, since that also works in inline code (and non-inline if remembering mathescape=true...)
• Two of the annotations are as previously only defined for value true, DocumentationClass and singleInstance. It may be best to remove the value, but in that case the text needs to be reformulated.
  • The absoluteValue was previously defined as =false in the syntax, but the text explained =true as well.
  • The defaultConnectionStructurallyInconsistent was previously defined as =true in the syntax, but the text specified "if true".
• The Icon and Diagram-layer already had both the old and this variant. In 18.6 they are defined with grammar-syntax, and then in 18.6.1.1 as records.

[maltelenz]

This seemingly opens up for expressions instead of the literals true or false for some of these. Does it? Do we want to?

[HansOlsson]

This seemingly opens up for expressions instead of the literals true or false for some of these. Does it? Do we want to?

Good point, and the answer to the latter is it depends
For some of them it makes sense to have it depend on an evaluable parameter, for others not; see previous discussion in #3375

[HansOlsson]

This seemingly opens up for expressions instead of the literals true or false for some of these. Does it? Do we want to?

Good point, and the answer to the latter is it depends For some of them it makes sense to have it depend on an evaluable parameter, for others not; see previous discussion in #3375

One possibility would be to change them to constant and parameter respectively, and state that constants must be given literal values and parameters must be evaluable.

[HansOlsson]

This seemingly opens up for expressions instead of the literals true or false for some of these. Does it? Do we want to?

Good point, and the answer to the latter is it depends For some of them it makes sense to have it depend on an evaluable parameter, for others not; see previous discussion in #3375

One possibility would be to change them to constant and parameter respectively, and state that constants must be given literal values and parameters must be evaluable.

I have now included that definition.

• I have deliberately not added it for other annotations, the idea is to add that in separate PRs once we have defined what it means. (So that we separately can discuss which ones must be evaluable or not after we have defined what it means at all.)
• The reason the Documentation-record was anyway updated (even though it wasn't touched by this PR previously) was that it seemed logical to have the common definition at the start of the chapter, the Documentation-definition relied on the unstated logic for records, and I believe it is fairly uncontroversial that the info-text shall be a literal.
• I use plain parameter for an evaluable parameter to keep it short; and similarly constant for literal.

Note in particular that the Figure-annotation isn't a parameter at all - since it directly refers to expressions for curves. (But the rest of it should likely be constant (or possibly parameter)).

[HansOlsson]

I would like some more input on this:

• Is it a good approach in general?
• Is it good to have the definition of parameter/constant and record at the start of the chapter?
• Is "misusing" parameter/constant for annotations a good idea? I know that we could use parameter ... annotation(Evaluate=true); to avoid one of the issues - but it will make the lines longer and harder to read.
• I similarly know that we can avoid the record-issue by having a differently named record class, and then a record component. That would be more correct, but more text to read. If some prefer the more correct approach I think we can discuss that in a separate PR. (No such record is added in this PR, it just describes how the existing ones work.)
• Can we merge this one as is, and then later discuss individual annotations? (Including which ones should be literal or evaluable parameters?)

[henrikt-ma]

I think we need to be more careful to not overload parameter and constant with other than the usual meanings.

This doesn't mean that I'm pushing for having, say, more constant than "literal" variability, but overall I would actually expect it to be possible to ease up variability requirements in the future to have less ad-hoc requirements to only support constant expressions in the form of literals.

[henrikt-ma]

The main remaining question seems to be what we can really promise regarding the presentation of component declaration style annotations – for which there has to exist a default behavior.

[henrikt-ma]

Default can be expressed with declaration equation:

Suggested change

	/*literal*/ constant String mayOnlyConnectOnce;
	/*literal*/ constant String mayOnlyConnectOnce = false;

[HansOlsson]

It's a string so false would be wrong. But could reformulate.

[HansOlsson]

I added a default and rephrased.

[henrikt-ma]

I feel we are ending up with a cumbersome notation if we always need to say that the annotation only has effect when present…

Suggested change

	It makes it an error if the connector does not appear as an inside connector in any connect-equation (for a conditional connector this check is only active if the connector is enabled).
	Only has effect when present, and makes it an error if the connector does not appear as an inside connector in any connect-equation (for a conditional connector this check is only active if the connector is enabled).

[HansOlsson]

I added a default and rephrased.

[henrikt-ma]

After making a couple of suggestions about complying with the notation we set out to follow, I am questioning the style we set for the default of component style annotations.

I think the default looks a lot like what one should write for making use of the annotation, which gets really confusing, especially for all the Boolean ones, where it looks as if one should specify the opposite of what the name suggests unless one pays attention to the text.

Take singleInstance for example. When looking at the synopsis, I see two things: the name singleInstance, and the value false. What I would like to see immediately is what to write in order to get the effect which is the purpose of the annotation.

Right now I don't have any concrete suggestion for what we might do instead, but I'd like to discuss this before I do the work of making more suggestions about complying with the current notation rules.

(It is a pity that we require the annotations to actually carry a modification, as the value tends to just be annoying and confusing for Boolean annotations.)

[HansOlsson]

Language group poll:
Explain defaults in text instead for annotations that only matter if set? For component-style annotation.

1. Don’t give the default, keep the rest, and require those strings to be non-empty.
2. Keep as is.

Anne (abstain), Henrik (abstain), Elena(1), Markus(1), Gerd(1), Dag(1), Hans (abstain).

Update.

[HansOlsson]

This has now been updated based on descision.