http://zorba.io/modules/xqdoc

View as XML or JSON.

The goal of xqDoc is to provide a simple vendor neutral solution for documenting XQuery modules, as well as tools to generate a user friendly presentation of this documentation and cross referencing information. Therefore, xqDoc proposes a new commenting convention that extends the currently defined XQuery comment style. This convention is modeled after Java's Javadoc commenting style, and provides a simple, uniform way to document XQuery source code. You can find more information about xqDoc on the website of the xqDoc project. This library module provides XQDoc utility functions.

Generating a user friendly presentation of the documentation is accomplished in the following steps:

  1. Module, variable, function, collection, and index declarations need to be commented using the xqDoc commenting conventions. For example, this module contains xqDoc-style comments
  2. A xqDoc-enabled processor can parse such documentation and generate a vendor neutral XML document which stores all the information about the code and the comments. Such a document adheres to the xqDoc Schema.
  3. The information of an XML document generated by the second step, can be transformed into arbitrary presentation formats (e.g. html).

This module implements the first and second step of this process. That is, Zorba can parse XQuery modules which are annotated with xqDoc-style documentation and generate the vendor neutral XML representation.

Function Summary

xqdoc-content ($module as xs:string) as element(*)

Generated the an XQDoc XML document for the module provided as parameter to this function.

xqdoc-content ($module as xs:string, $options as element(opt:enable)) as element(*)

Generated the an XQDoc XML document for the module provided as parameter to this function.

xqdoc ($module-uri as xs:string) as element(*)

Generates an XQDoc XML document for the module located at the URI provided as parameter to this function.

xqdoc ($module-uri as xs:string, $options as element(opt:enable)) as element(*)

Generates an XQDoc XML document for the module located at the URI provided as parameter to this function.

Functions

xqdoc-content#1

declare  function xqd:xqdoc-content($module as xs:string) as element(*)
Generated the an XQDoc XML document for the module provided as parameter to this function.

Parameters

module as xs:string
The module (as string) for which to generate the XQDoc documentation.

Returns

element(*)
An element according to the xqdoc schema (http://zorba.io/modules/xqdoc.xsd).

xqdoc-content#2

declare  function xqd:xqdoc-content($module as xs:string, $options as element(opt:enable)) as element(*)
Generated the an XQDoc XML document for the module provided as parameter to this function. In comparison to the single parameter version, this function does not generate XQDoc for all language components. By default, the following components are deactivated: XQuery comments, import statements, variable declarations, function declarations, collection declarations, and index declarations. The second parameter is used to enable the XQDoc generation of those components.

Parameters

module as xs:string
The module (as string) for which to generate the XQDoc documentation.
options as element(opt:enable)
XQDoc generation options, e.g.:
 <enable xmlns="http://zorba.io/modules/xqdoc-options" comments="true" functions="true" indexes="true" > 

Returns

element(*)
An element according to the xqdoc schema (http://zorba.io/modules/xqdoc.xsd).

xqdoc#1

declare  %an:nondeterministic function xqd:xqdoc($module-uri as xs:string) as element(*)
Generates an XQDoc XML document for the module located at the URI provided as parameter to this function.

Parameters

module-uri as xs:string
The URL of the module for which to generate XQDoc.

Returns

element(*)
An element according to the xqdoc schema (http://zorba.io/modules/xqdoc.xsd).

xqdoc#2

declare  function xqd:xqdoc($module-uri as xs:string, $options as element(opt:enable)) as element(*)
Generates an XQDoc XML document for the module located at the URI provided as parameter to this function. In comparison to the single parameter version, this function does not generate XQDoc for all language components. By default, the following components are deactivated: XQuery comments, import statements, variable declarations, function declarations, collection declarations, and index declarations. The second parameter is used to enable the XQDoc generation of those components.

Parameters

module-uri as xs:string
The URL of the module for which to generate XQDoc.
options as element(opt:enable)
XQDoc generation options, e.g.:
 <enable xmlns="http://zorba.io/modules/xqdoc-options" comments="true" functions="true" indexes="true" /> 

Returns

element(*)
An element according to the xqdoc schema (http://zorba.io/modules/xqdoc.xsd).