Extend xqdoc format to capture XQuery 3 annotations #24

Open
apb2006 opened this Issue Feb 12, 2013 · 11 comments

Projects

None yet

7 participants

@apb2006
Contributor
apb2006 commented Feb 12, 2013

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.

@apb2006
Contributor
apb2006 commented Feb 13, 2013
@apb2006
Contributor
apb2006 commented Feb 13, 2013

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
jfix commented Jan 4, 2014

👍

@adamretter

Yes please.

On 4 June 2013 13:36, Christian Gruen notifications@github.com 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
Contributor
apb2006 commented Jan 5, 2014

looks good to me.

@ChristianGruen

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment