Re: Improving support for user-defined annotations

Would you like to draft a concrete proposal indicating textual changes to the spec?

Michael Kay
Saxonica

> On 17 Dec 2020, at 08:26, Reece Dunn <msclrhd@googlemail.com> wrote:
> 
> With XQuery 3.0 annotations were extended to support any EQName, and allow optional values. These have been used by vendors to implement REST capabilities (via the EXQuery RESTXQ specification) and unit test capabilities (such as in BaseX's test module).
> 
> However, support for user-defined annotations is lacking. This means that external projects implementing the RESTXQ module (such as the rqx library for MarkLogic) need to rely on vendor extensions and vendor APIs to implement that functionality to take advantage of annotations. A similar case applies to unit test libraries like XRay which use annotations to define which functions are unit tests.
> 
> The general approach for this (some of which have been raised as xpath-ng proposals) can be broken down into 3 parts:
> 
> 1. Annotation Item Types -- similar to a FunctionTest, making annotations a concrete part of the XQuery type system.
> 
> 2. Annotation Declarations -- similar to function declarations, that define the form an annotation can take; that is, the annotation name along with the supported parameter names and types.
> 
> 3. Functions and Operators support -- allowing annotations to be queried, along with the annotation argument values, and possibly other operations.
> 
> I'm wondering if it makes sense for annotation declarations to be function declarations. This would avoid the need for having a separate parallel system to functions (including in-scope definitions).
> 
> For example, you could create a simple test framework as follows:
> 
>     declare %annotation function test:case() {};
>     declare %annotation function test:values($values as item() ...) {};
> 
>     declare function test:run-tests() {
>         for $f in in-scope-functions()
>         let $a as annotation()? :=
>             annotation-for-function($f, test:case#0)
>         let $with-values as annotation(xs:string ...)* :=
>             annotation-for-function($f, test:values#*) (: any arity :)
>         where exists($a)
>         return if (exists($with-values))
>             then
>                 for $value in $with-values
>                 return $f(annotation-arguments($value))
>             else $f()
>     };
> 
> and have it work on any XQuery 4.0 capable processor.
> 
> The other use case for this is for tooling, so things like xqDoc can provide documentation for annotations and annotation parameters, as well as accessing the annotation information in a vendor-agnostic manner to generate the function signatures in the documentation. Editors/IDEs could also provide features like validation, auto-complete, and parameter signature tooltips for user-defined annotations.
> 
> Kind regards,
> Reece