XQuery for eXist - eXist: A NoSQL Database and Application Development Platform - page 125

XQuery Documentation with xqDoc
xqDoc is an effort to standardize XQuery documentation in a similar vein to how
JavaDoc has for Java. xqDoc works by reading specialized comments you insert into
your XQuery code. A parser can then use these to extract additional information
about your module, its (global) variables, and its functions. This information could
then, for example, be used to display details about a module to the user. The eXist
function browser is a good example of an implementation which uses xqDoc to ach‐
ieve exactly that.
Here is an example of a little module containing xqDoc information:
xquery version "1.0" encoding "UTF-8" ;
(:~
: Example module with xqDoc information
:
: @version 1.0
: @author Erik Siegel
:)
module namespace xquerydoc = "http://www.exist-db.org/book/XQueryDoc" ;
(:~
: Example dummy function
:
: @param $in The input to the function
:)
declare function xquerydoc:test ( $ in as xs:string + ) as xs:string
{
'Dummy'
};
All comments starting with (:~ are parsed by the xqDoc parser. Keywords in these
comments start with an @ character. The exact syntax can be found on the xqDoc
website .
eXist has an inspect extension module to work with xqDoc. The functions in this
module return an XML representation of the module's content, including possible
annotations by the xqDoc comments. For instance, running inspect:inspect on the
preceding example module returns:
<module uri= "http://www.exist-db.org/book/XQueryDoc" prefix= "xquerydoc" >
<description> Example module with xqDoc information </description>
<author> Erik Siegel </author>
<version> 1.0 </version>
<variable name= "xquerydoc:global" type= "xs:string" cardinality= "exactly one" />
<function name= "xquerydoc:test"
module= "http://www.exist-db.org/book/XQueryDoc" >
<argument type= "xs:string" cardinality= "one or more" var= "in" >
The input to the function </argument>
<returns type= "xs:string" cardinality= "exactly one" />