I was probably not concentrating very well while annotation assertions were being discussed; I think I assumed that all would become clear when I read the final spec. In fact, for someone who wasn't listening to the debates at the time, the spec is as clear as mud.

Let's start with the definition:

[Definition: If an annotation is present in a FunctionTest, it is called an annotation assertion.]

Well, for a start, this is a very odd sort of definition. It's a bit like saying that if an apple is present in a restaurant it is called a dessert. This leaves me confused as to whether all apples are desserts or whether all desserts are apples. It might be better to define the concept syntactically:

[189]   	FunctionTest	   ::=   	AnnotationAssertion* (AnyFunctionTest
| TypedFunctionTest)

[189a] AnnotationAssertion ::= Annotation

Here it's no longer true that an AnnotationAssertion IS an annotation, it just takes the same syntactic form as an annotation.

The next thing we read is "Annotation assertions further restrict the set of functions that are matched by a FunctionTest." So, I want to know how. I know that %speed:fast is an annotation, so I might conclude that it is also an annotation assertion, and with some imagination I might conclude that a FunctionTest carrying this assertion will only match functions with this annotation. But the spec doesn't actually say that. Perhaps (my imagination is now going wild, there is nothing in the spec to say otherwise) the annotation assertion %speed:fast will also match a function annotated as %speed:superfast. If that's a possibility, I think the spec should say so. There certainly needs to be something to describe the relationship between annotation assertions and annotations.

Read on, Macduff. "Implementations MAY define further annotation assertions, whose behaviour is implementation-defined." What does "further" mean? Does it mean assertions that don't take the syntactic form of an annotation? I suspect not. I suspect it means annotation assertions that are not defined in this spec. The set of annotation assertions defined in this spec appears to be empty, is that right? So "further" is a bit of a euphemism. ("Behaviour", incidentally, needs to be spelt the American way).

Moving on: "Implementations MAY provide a way for users to create their own annotation assertions.". So my assumption that you create an annotation assertion merely by using an annotation within a FunctionTest is clearly wrong. That's what the definition implied, but it seems that not every apple found within a restaurant is ipso facto a dessert. This is confirmed by the first Note: "There are no annotation assertions that correspond to the %public and %private annotations."  So I'm coming to the conclusion that the only assertions that can be used as annotation assertions are those that are explicitly licensed to be used in that way by some mechanism outside this specification. Which presumably means there is some error condition that needs to be added to the spec to disallow others. (Or perhaps it isn't an error, perhaps they are just ignored? In which case we need to be clear about whether an annotation assertion that's ignored is or is not an annotation assertion).

We're getting close to the end "Other specifications in the XQuery family also use annotation assertions.". Perhaps, I'm feeling, the "also" is redundant? Perhaps what has happened is that XQuery itself doesn't use them at all, but they are available for use by other specifications? If so, that's what we should say.