Note: this is an edited version of a previous tutorial we updated to run with Zorba 2.0.

xqDoc is the de facto industry standard for generating API documentation from XQuery modules. xqDoc style comments begin with a ‘(:~’ and end with a ‘:)’ (see code snippet below).

(:~
 : This library module provides simple file system I/O operations.
 :
 : @author Gabriel Petrovay
 : @version 1.0 
 :)
module namespace file = "http://www.zorba-xquery.com/modules/file";

More information about the xqDoc specification is available on the xqDoc website.

Overview

Zorba 1.4 provides built-in xqDoc support which doesn’t require any installation or configuration. In general, creating documentation from an XQuery module that is documented with xqDoc is a two step process:

• Given a module as input, one creates a valid xqDoc document.
• This xqDoc document can be converted to formats such as XHTML or DocBook.

In Zorba, the first step is accomplished by using the built-in xqDoc module. This module provides functions whose result given a documented module is a valid xqDoc document.

In a first step, the filename lib.xq of the documented module is passed as an argument to the xqdoc() function of Zorba’s xqDoc module. This function returns a valid xqDoc document containing information about the module. In a second step, this document is transformed (using XQuery) into a nicely presented HTML document. In the following sections, we describe each of those steps in more detail.

Generating an xqDoc Document

The module that can be used to generate xqDoc documents is available using the target namespace http://www.zorba-xquery.com/modules/xqdoc. This module contains two functions both returning xqDoc documents given a (documented) XQuery module as input: xqdoc:xqdoc() and xqdoc:xqdoc-content(). The former function takes the URI of the documented module as a string. The argument of the latter function is the XQuery module itself.

For instance, the following XQuery program generates the xqDoc document for the xqDoc module itself.

import module namespace xqdoc = "http://www.zorba-xquery.com/modules/xqdoc";

xqdoc:xqdoc("http://www.zorba-xquery.com/modules/xqdoc")

You can try this example live.

An excerpt of the result looks as follows:

<?xml version="1.0" encoding="UTF-8"?>
<xqdoc:xqdoc xmlns:xqdoc="http://www.xqdoc.org/1.0">
<xqdoc:control>
  <xqdoc:date>2012-09-23T15:52:10.06Z</xqdoc:date>
  <xqdoc:version>1.0</xqdoc:version>
</xqdoc:control>
<xqdoc:module type="library">
  <xqdoc:uri>http://www.zorba-xquery.com/modules/xqdoc</xqdoc:uri>
  <xqdoc:name>xqdoc</xqdoc:name>
  <xqdoc:comment>
    <xqdoc:description> <p>
 The goal of xqDoc is to provide a simple vendor neutral solution for...

Alternatively, if you want to generate xqDoc document out of the string representation of a module (maybe because it’s not available as a file or built-in module), you can pass the contents of the module as a parameter to the xqdoc:xqdoc-content() function. For example, the following XQuery program retrieves the functx module using http and returns the documentation.

import module namespace http  = "http://expath.org/ns/http-client";
import module namespace xqdoc = "http://www.zorba-xquery.com/modules/xqdoc";

let $module-uri := "http://www.xqueryfunctions.com/xq/functx-1.0-doc-2007-01.xq"
let $module     := http:send-request(<http:request href="{$module-uri}" method="get" />)[2]
let $xqdoc      := xqdoc:xqdoc-content($module)
return $xqdoc

You can try this example live.

Transforming xqDoc Documents

Given a valid xqDoc document, it can be easily translated into a variety of formats such as XHTML or DocBook. Zorba provides an XQuery module that can be used to transform xqDoc documents into XHTML. The following XQuery program demonstrates how easy it is to generate nice XHTML documentation using the xqDoc module and a simple stylesheet (written in XQuery) that converts xqDoc XML to XHTML:

import module namespace xqdoc = "http://www.zorba-xquery.com/modules/xqdoc";
import module namespace html-stylesheet = "http://www.zorba-xquery.com/modules/xqdoc/html"
                                                   at "http://zorba.s3.amazonaws.com/html.xq";

let $xqdoc := xqdoc:xqdoc("http://www.zorba-xquery.com/modules/xqdoc")
return html-stylesheet:convert($xqdoc)

You can try this example live.

Examples, Extensions, & Contact

More examples showing documentation generated by the Zorba xqDoc modules are available at

• Zorba’s module documentation page
• 28msec’s module documentation page

Zorba is extending the original xqDoc specification to make the information available in xqDoc documents even more useful. Specifically, the xqDoc documents generated by Zorba add an additional attribute named arity to the xqdoc:name element of a function. This allows to disambiguate references to functions having the same name but a different arity.

If you have questions or comments regarding Zorba or its xqDoc support, feel free to write an email to the zorba-users mailing list.