Start clearing up annotation syntax for functions.

[HansOlsson]

It is intended to work towards close #3495 - but it doesn't handle all of the annotations as some are problematic.

Note that I deliberately added default values in some cases, I believe they are the correct ones.

It might be that we should add more, or view this as enough to close it - and later think about the rest.

The problem with the other ones are:

• "Trivial": the external function ones can specify either an array or a scalar.
• "Messy": The derivative and inline-annotations don't fit into the pattern for two reasons:
  • The "value" is not a value - so no good type for the declaration (it is a function for derivatives, and something else for inverse)
  • The optional sub-modifiers for values, like smoothOrder(normallyConstant=x)=2

(I have might have missed some that could be handled.)

[eshmoylova]

I updated the description to make it a link to the issue #3495 for an easy lookup.

[henrikt-ma]

Suggesting minor change that will make this more compatible with #3621.

[henrikt-ma]

I thought we decided to avoid writing out defaults like this, as it gives the impression that LateInline = false is what one is supposed to write?

[HansOlsson]

As I recall the idea was not use the form when specifying the default literal value (assuming it exists), when it is so "normal" that specifying it would look like an error (like singleInstance).

Different inlining variant and GenerateEvents don't fall under that; and is more similar to absoluteValue.

[henrikt-ma]

That's not how I recall it. For me, the main problem which was resolved when removing all those defaults was that what the reader sees first shouldn't be something one normally doesn't write when using the annotation. This was avoided by drastically reducing the use of declaration equations for explaining defaults in case of component style annotations.

I find LateInline similar to DocumentationClass, for which the default was removed in aa6ce47.

[HansOlsson]

To me these two explanations are fairly similar.
We agree that using DocumentationClass = false does not really make sense at all in practice, the point is that LateInline = false is just a bit unusual - one can easily see someone experimenting with setting LateInline to true or false to test the result.

And most of the removed defaults in that commit weren't literal values, but explanations as defaults.

[henrikt-ma]

OK, so we have different recollections of the exact formulations used in the meeting discussions behind removing literal defaults. Fine.

Now, if we think about how to write clear specification text, don't you agree that there is a problem with picking the style of presentation based on vague opinions about what is more or less unusual or odd? … that specifying defaults for component style annotations sometimes with declaration equation and sometimes in text (even when the default corresponds to a literal value), is causing more confusion than useful brevity?

[HansOlsson]

But we have lots of annotations with defaults, so introducing a rule saying that we shouldn't use defaults doesn't make sense.

The following are some annotations that are defined with defaults: Documentation.info, Documentation.revisions, Documentation.figures (and many sub-elements), Documentation.styleSheets, experiment.StartTime, and for graphical items origin, rotation, preserveAspectRatio, initalScale, visible, primitivesVisible, fontSize, textColor, color, pattern, ....

Thinking more it might be that we should reconsider the previous idea of not using defaults in some cases.

[henrikt-ma]

There's a difference between component style annotations and record style annotations. As far as I can see, all of your examples are within such records:

• Documentation, experiment, GraphicItem, CoordinateSystem, Text

The point I am raising in this thread is about component style annotations.

[henrikt-ma]

I'm afraid defaults should be presented in the text rather than as a default binding.

[HansOlsson]

Language group: Describe these in text (not as default), and then later revisit all.

[HansOlsson]

Language group: Describe these in text (not as default), and then later revisit all.

This has now been implemented. @henrikt-ma

[henrikt-ma]

Above, the default was described after giving the meaning of Inline = false. It would make sense to be consistent and describe the default after the meaning of LateInline = false.

[henrikt-ma]

Trying to fix some language:

Suggested change

	The default for late inlining is tool-specific, in particular tools may automatically delay inlining to differentiate or possible invert the function before inlining it.
	The default for late inlining is tool-specific.
	In particular, tools may automatically delay inlining in order to take advantage of function annotations for derivatives and inverses.

[henrikt-ma]

How about swapping order with the previous sentence, and then have a paragraph break before the rule about combining annotations?

[henrikt-ma]

Basically good, but there was at least one need for improved language.