Annotations: Editorial notes

[ChristianGruen]

Copied from #710 (review):

For avoidance of doubt, we should say in XQuery 4.6.2.4 (Named Function References) that the function created by a named function reference has its annotations taken from the function definition. There are other places where we are not explicit about the annotations of a function item, for example with partial function application. We should add a note that in XPath and XSLT, it is not possible to define function annotations, so this function will always return an empty result. (However, we should consider giving user-defined functions in XSLT annotations based on their attributes, e.g. visibility and streamability).

…and my complementary note in the PR thread:

I decided to merge the PR without changes, and not add the reference to XPath and XSLT, because the function may also return results for XQuery functions imported via fn:load-xquery-module.

Additional notes from today’s meeting:

• For annotations without values, we could assign true() as a default value.
• Examples could be added to fn:function-annotations to demonstrate how to check for annotations without values (or with values whose EBV is false(): 0, "", etc.).
• Dimitre suggested restructuring the spec for features that are not available in XPath.
• Maybe annotations would also be helpful in XPath.

Feel free everyone to add more comments.

[rhdunn]

As Michael Kay noted, annotations are part of the function signature in the Data Model spec, even if languages like XPath don't define them:

The presence of annotations is language dependent; functions defined in languages, such as XPath, that have no mechanism for defining annotations will create functions in the data model with zero annotations.

[liamquin]

it would be nice if expressions could be moved between XQuery and XPath wherever possible. I'd like to see annotations available in XPath. Ackermann's Function runs much faster if you cache the results, albeit using large amounts of memory :)

[dnovatchev]

• Dimitre suggested restructuring the spec for features that are not available in XPath.

Only as a temporary step, before either it is moved to the XQuery Specification, or annotations are added to XPath.

In case we have no annotations capability in XPath, this function remains XQuery-specific and its place is exactly in the XQuery specification.

[dnovatchev]

…and my complementary note in the PR thread:

I decided to merge the PR without changes, and not add the reference to XPath and XSLT, because the function may also return results for XQuery functions imported via fn:load-xquery-module.

Again, this pre-supposes that the XPath user knows XQuery and its annotations mechanism, which in general is not the case.

Typically a user may need to access a function that is defined in XQuery, without needing its annotations, and not being aware at all that "annotations" exist, or whatever "annotations" may represent/stand-for.

As a user advocate I stand firmly against polluting the specifications - having clear boundaries minimizes the confusion of the readers.

[dnovatchev]

As Michael Kay noted, annotations are part of the function signature in the Data Model spec, even if languages like XPath don't define them:

The presence of annotations is language dependent; functions defined in languages, such as XPath, that have no mechanism for defining annotations will create functions in the data model with zero annotations.

This must be part of the description of the function, in order to avoid the otherwise inevitable confusion in most of any reader who is not using XQuery.

@ChristianGruen, please confirm that the above text will be added.

[dnovatchev]

it would be nice if expressions could be moved between XQuery and XPath wherever possible. I'd like to see annotations available in XPath. Ackermann's Function runs much faster if you cache the results, albeit using large amounts of memory :)

@liamquin Before doing that we need a quick tutorial on what annotations are, and what they are designed to achieve. Also about their scope and life-cycle.

As for caching, any "caching-annotation" is equivalent to a caching-decorator and with the introduction of decorators in XPath such annotation will not be needed.

[michaelhkay]

Unfortunately we already have the function load-query-module(), so an XPath user must either have some understanding of XQuery or ignore the existence of this function.

Exactly the same applies to the function-annotations() function.

In fact it might well be that a primary use case for using function-annotations in XPath is where the XPath users wants to take advantage of an XQuery function library in this way: the annotations might be used to decide which functions to import.

We're spending an awful lot of time deciding where to draw the boundaries between XPath and XQuery, and the reason it takes a long time to decide is that we have no consensus on the criteria we should apply when making the decision.

[dnovatchev]

Unfortunately we already have the function load-query-module(), so an XPath user must either have some understanding of XQuery or ignore the existence of this function.

If I am a user that doesn't know anything about XQuery and only knows that the function, when called with specific arguments produces specific, wanted result, I would definitely use load-xquery-module in order to access and call this function, regardless of what XQuery code implementation it has. The function is a black-box that still produces the wanted result.

The same definitely applies on any other function that is not written by the caller.

Thus, any such user is not interested in the implementation details, including this function's "annotations" - whatever this might mean.

[michaelhkay]

any such user is not interested in the implementation details

They might well be interested in details such as "%requires-schema-aware-processor(true())".

Generally I belong to the "keep XPath as small as possible" camp. But there are benefits in the fact that XPath and XQuery have exactly the same function library, and I don't want to lose that.

[dnovatchev]

any such user is not interested in the implementation details

They might well be interested in details such as "%requires-schema-aware-processor(true())".

Generally I belong to the "keep XPath as small as possible" camp. But there are benefits in the fact that XPath and XQuery have exactly the same function library, and I don't want to lose that.

I am not against adding "annotations" to XPath, just waiting to see what might be proposed and to be able to evaluate it.

Till then, returning "annotations" from a function would be premature - like putting the cart before the horse.

Also, it seems that (at least what I am trying to understand about "annotations") these behave similarly to some types of decorators but might be "more static" and thus not always flexible and usable. This is why I asked about the scope and life-cycle of "annotations".

[dnovatchev]

any such user is not interested in the implementation details

They might well be interested in details such as "%requires-schema-aware-processor(true())".

Generally I belong to the "keep XPath as small as possible" camp. But there are benefits in the fact that XPath and XQuery have exactly the same function library, and I don't want to lose that.

Annotations are kind of attributes of the type object. Let us have the type object as a first-class citizen of the language, then annotations can be part of the attributes/properties of any type, or of an instance of a particular type.

[ChristianGruen]

@ChristianGruen, please confirm that the above text will be added

I can help you create a little editorial pull request, you can then decide which phrases you want be added and where they should be placed in the text.

[michaelhkay]

The WG agreed to close this with no action on 2024-04-09.