New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Extend xqdoc format to capture XQuery 3 annotations #24

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

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.

@jpcs

This comment has been minimized.

Show comment
Hide comment
@apb2006

This comment has been minimized.

Show comment
Hide comment
@apb2006
Contributor

apb2006 commented Feb 13, 2013

@apb2006

This comment has been minimized.

Show comment
Hide comment
@apb2006

apb2006 Feb 13, 2013

Contributor

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?

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

This comment has been minimized.

Show comment
Hide comment
@ChristianGruen

ChristianGruen 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 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

This comment has been minimized.

Show comment
Hide comment
@ChristianGruen

ChristianGruen 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?

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

This comment has been minimized.

Show comment
Hide comment
@wcandillon

wcandillon Jun 4, 2013

Looks good.

wcandillon commented Jun 4, 2013

Looks good.

@lcahlander

This comment has been minimized.

Show comment
Hide comment
@lcahlander

lcahlander Jun 5, 2013

Looks good.

lcahlander commented Jun 5, 2013

Looks good.

@jfix

This comment has been minimized.

Show comment
Hide comment
@jfix

jfix commented Jan 4, 2014

👍

@adamretter

This comment has been minimized.

Show comment
Hide comment
@adamretter

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

Adam Retter

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

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

Adam Retter

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

@apb2006

This comment has been minimized.

Show comment
Hide comment
@apb2006

apb2006 Jan 5, 2014

Contributor

looks good to me.

Contributor

apb2006 commented Jan 5, 2014

looks good to me.

@ChristianGruen

This comment has been minimized.

Show comment
Hide comment
@ChristianGruen

ChristianGruen Jan 14, 2014

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

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 join this conversation on GitHub. Already have an account? Sign in to comment