Skip to content
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
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 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 jpcs commented Feb 13, 2013

@apb2006
Copy link
Contributor Author

@apb2006 apb2006 commented Feb 13, 2013

@apb2006
Copy link
Contributor Author

@apb2006 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 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 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 wcandillon commented Jun 4, 2013

Looks good.

1 similar comment
@lcahlander
Copy link

@lcahlander lcahlander commented Jun 5, 2013

Looks good.

@jfix
Copy link

@jfix jfix commented Jan 4, 2014

👍

@adamretter
Copy link

@adamretter 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 apb2006 commented Jan 5, 2014

looks good to me.

@ChristianGruen
Copy link

@ChristianGruen 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
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
7 participants
You can’t perform that action at this time.