Skip to content
This repository has been archived by the owner. It is now read-only.

Extend xqdoc format to capture XQuery 3 annotations #24

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

Extend xqdoc format to capture XQuery 3 annotations #24

apb2006 opened this issue Feb 12, 2013 · 11 comments

Comments

@apb2006
Copy link
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.

@jpcs
Copy link
Collaborator

jpcs commented Feb 13, 2013

@apb2006
Copy link
Contributor Author

apb2006 commented Feb 13, 2013

Some discussion on the Zorba user list

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

@apb2006
Copy link
Contributor Author

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
Copy link

ChristianGruen commented Jun 1, 2013

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
Copy link

ChristianGruen commented Jun 4, 2013

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
Copy link

wcandillon commented Jun 4, 2013

Looks good.

1 similar comment
@lcahlander
Copy link

lcahlander commented Jun 5, 2013

Looks good.

@jfix
Copy link

jfix commented Jan 4, 2014

👍

@adamretter
Copy link

adamretter commented Jan 5, 2014

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//issues/24#issuecomment-18905932
.

Adam Retter

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

@apb2006
Copy link
Contributor Author

apb2006 commented Jan 5, 2014

looks good to me.

@ChristianGruen
Copy link

ChristianGruen commented Jan 14, 2014

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

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

No branches or pull requests

7 participants