XQuery/Generating xqDoc-based XQuery Documentation

Motivation

You want to create high-quality documentation of your XQuery functions and modules.

Method

xqDoc is a standard for formatting comments in XQuery modules. The eXist system comes with a XQuery module which parses XQuery modules containing comments in this format and generates XML in the xqDoc XML format. This XML can then be transformed into other formats such as HTML, PDF, DocBook or ePub.

eXist-db provides a module xdbm with functions to generate an xqDoc document from an XQuery module.

Sample XQuery module

xquery version "1.0";

(:~
: This is a simple module which contains a single function
: @author Dan McCreary
: @version 1.0
: @see http://xqdoc.org
:
:)
module namespace simple = "http://simple.example.com";

(:~
 : this function accepts  two integers and returns the sum
 :
 : @param $first - the first number 
 : @param $second - the second number
 : @return the sum of $first and $second
 : @author Dan McCreary
 : @since 1.1
 : 
:)
declare function simple:add($first as xs:integer, $second as xs:integer) as xs:integer {
   $first + $second
};

Generating the XML

You can generate an xqdoc file from an XQuery module using the xqdm:scan function:

xquery version "1.0";
let $module_path := "xmldb:exist:///db/apps/xqbook/documentation/simple-module.xqm"
let $my-doc := xqdm:scan(xs:anyURI($module-path))
return $my-doc

Note that the string must be converted to a data type of anyURI.

Execute this script

Sample xqDoc Output

The scanner will generate the following XML:

<xqdoc:xqdoc xmlns:xqdoc="http://www.xqdoc.org/1.0">
    <xqdoc:control>
        <xqdoc:date>Mon Mar 15 22:34:08 GMT 2010</xqdoc:date>
        <xqdoc:version>1.0</xqdoc:version>
    </xqdoc:control>
    <xqdoc:module type="library">
        <xqdoc:uri>http://simple.example.com</xqdoc:uri>
        <xqdoc:name>/db/Wiki/eXist/xqdoc/test.xqm</xqdoc:name>

        <xqdoc:comment>
            <xqdoc:description> This is a simple module which contains a single function</xqdoc:description>
            <xqdoc:author> Dan McCreary</xqdoc:author>
            <xqdoc:version> 1.0</xqdoc:version>
            <xqdoc:see> http://xqdoc.org</xqdoc:see>

        </xqdoc:comment>
        <xqdoc:body xml:space="preserve">xquery version "1.0";

(:~
: This is a simple module which contains a single function
: @author Dan McCreary
: @version 1.0
: @see http://xqdoc.org
:
:)
module namespace simple = "http://simple.example.com";

(:~
 : this function accepts  two integers and returns the sum
 :
 : @param $first - the first number 
 : @param $second - the second number
 : @return the sum of $first and $second
 : @author Dan McCreary
 : @since 1.1
 : 
:)
declare function simple:add($first as xs:integer, $second as xs:integer) as xs:integer {
   $first + $second
};
</xqdoc:body>
    </xqdoc:module>
    <xqdoc:functions>
        <xqdoc:function>
            <xqdoc:comment>
                <xqdoc:description> this function accepts  two integers and returns the sum</xqdoc:description>

                <xqdoc:author> Dan McCreary</xqdoc:author>
                <xqdoc:param> $first - the first number </xqdoc:param>
                <xqdoc:param> $second - the second number</xqdoc:param>
                <xqdoc:return> the sum of $first and $second</xqdoc:return>
                <xqdoc:since> 1.1 </xqdoc:since>

            </xqdoc:comment>
            <xqdoc:name>add</xqdoc:name>
            <xqdoc:signature>add($first as xs:integer, $second as xs:integer) as xs:integer</xqdoc:signature>
            <xqdoc:body xml:space="preserve">declare function simple:add($first as xs:integer, $second as xs:integer) as xs:integer{
   $first + $second
};</xqdoc:body>
        </xqdoc:function>
    </xqdoc:functions>
</xqdoc:xqdoc>

Known Problems

The parser for the XQuery doc is slightly different than the standard XQuery parser for eXist. In some cases an XQuery that works with eXist will fail under the XQDocs parser.

• old-style variable declarations are still supported in eXist but not by the xqDoc parser

For example the following variable declaration:

  declare variable $foo:bar { 'Hello World' };

is valid in eXist XQuery but this syntax is not valid in xqDoc which only supports the XQuery standard declaration e.g.

 declare variable $foo:bar := 'Hello World';

• comments must be valid XML text. This is more restrictive than in XQuery. For example < and & must be expressed as &lt; and &amp;