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.

Generating the XML
You can generate an xqdoc file from an XQuery module using the xqdm:scan function: Note that the string must be converted to a data type of anyURI.

[/documentation/make-simple-xqdoc.xq Execute this script]

Sample xqDoc Output
The scanner will generate the following XML:

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.

For example the following variable declaration:
 * old-style variable declarations are still supported in eXist but not by the xqDoc parser

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 &amp;lt; and &amp;amp;