Extend xqdoc format to capture XQuery 3 annotations

[apb2006]

It would be good if the xqdoc XML format included information about annotations in the source. One use for this is documenting RESTXQ applications

I believe the Zorba xqdoc module is already doing this http://www.zorba-xquery.com/html/modules/zorba/xqdoc/xqdoc Although I cant find any documentation for this.

[jpcs]

Zorba's schema for XQDoc annotations is here:

http://bazaar.launchpad.net/~zorba-coders/zorba/trunk/view/head:/modules/com/zorba-xquery/www/modules/xqdoc.xsd

[apb2006]

Some discussion on the Zorba user list

https://groups.google.com/forum/?fromgroups=#!topic/zorba-users/J8rDpF6y6Fg

[apb2006]

The proposal at https://bugs.launchpad.net/zorba/+bug/1124374 looks good to me

%restxq:form-param("message","{$message}", "'no message delivered'", 5)

results in

<xqdoc:annotation prefix="restxq" namespace="" localname="form-param"/>
  <xqdoc:literal type="string" value="message"/>
  <xqdoc:literal type="string" value="{$message}"/>
  <xqdoc:literal type="string" value="'no message delivered'"/>
  <xqdoc:literal type="numeric" value="5"/>
</xqdoc:annotation>

where the order of the literal elements reflects the order of the literals in the annotation.

@adamretter Does Existdb have any opinions in this area?

[ChristianGruen]

We just added an Inspection Module to BaseX that provides both an xqDoc and a custom documentation function. After having some discussion on the existing xqDoc schema, we eventually did the following:

• we added an xqdoc:annotations element to each variable or function that uses annotations. Similar to Zorba’s proposal, the xqdoc:annotation child nodes may have additional xqdoc:literal nodes with type attributes (xs:string, xs:integer, xs:decimal, xs:double) and values. We decided to use a single name attribute, as this is closer to the existing xqDoc conventions.
• as the current xqDoc conventions say nothing about how prefixes are to be bound, we added a xqdoc:namespaces element to the root element, which summarizes all prefixes and namespace URIs used or declared in the module.
• similar to xquerydoc (but contrary to the current official xqDoc schema), we added name and type elements to variables.

As a result, Andy’s RESTXQ example results in the following output:

  <xqdoc:namespaces>
    <xqdoc:namespace prefix="restxq" uri="http://exquery.org/ns/restxq"/>
  </xqdoc:namespaces>
  ...
  <xqdoc:annotations>
    <xqdoc:annotation name="restxq:form-param">
      <xqdoc:literal type="xs:string">message</xqdoc:literal>
      <xqdoc:literal type="xs:string">{$message}</xqdoc:literal>
      <xqdoc:literal type="xs:string">'no message delivered'</xqdoc:literal>
      <xqdoc:literal type="xs:integer">5</xqdoc:literal>
    </xqdoc:annotation>
  </xqdoc:annotations>

Feeback is welcome!

[ChristianGruen]

I talked to Darin McBeath, and we would now be interested in what you all think about the proposed xqDoc extensions… Would you be like to see the schema extended the way it has been proposed in my last comment?

[wcandillon]

Looks good.

[lcahlander]

Looks good.

[jfix]

:+1:

[adamretter]

Yes please.

On 4 June 2013 13:36, Christian Gruen [email protected] wrote:

I talked to Darin McBeath, and we would now be interested in what you all think about the proposed xqDoc extensions… Would you be like to see the schema extended the way it has been proposed in my last comment?

— Reply to this email directly or view it on GitHubhttps://github.com/xquery/xquerydoc/issues/24#issuecomment-18905932 .

Adam Retter

skype: adam.retter tweet: adamretter http://www.adamretter.org.uk

[apb2006]

looks good to me.

[ChristianGruen]

Darin hast just updated xqdoc.org with the proposed changes. Thanks all for your feedback!