XQuery/使用 xqDoc 生成 XQuery 文档

动机

您希望为您的 XQuery 函数和模块创建高质量的文档。

方法

xqDoc 是一种在 XQuery 模块中格式化注释的标准。eXist 系统附带一个 XQuery 模块，该模块解析包含此格式注释的 XQuery 模块并生成 xqDoc XML 格式的 XML。然后可以将此 XML 转换为其他格式，例如 HTML、PDF、DocBook 或 ePub。

eXist-db 提供了一个模块 xdbm，它包含用于从 XQuery 模块生成 xqDoc 文档的函数。

示例 XQuery 模块

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
};

生成 XML

您可以使用 xqdm:scan 函数从 XQuery 模块生成 xqdoc 文件

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

请注意，字符串必须转换为 anyURI 数据类型。

执行此脚本

示例 xqDoc 输出

扫描程序将生成以下 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>

已知问题

XQuery 文档的解析器与 eXist 的标准 XQuery 解析器略有不同。在某些情况下，在 eXist 中有效的 XQuery 将在 XQDocs 解析器下失败。

旧式变量声明在 eXist 中仍然受支持，但在 xqDoc 解析器中不受支持

例如，以下变量声明

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

在 eXist XQuery 中有效，但此语法在 xqDoc 中无效，xqDoc 仅支持 XQuery 标准声明，例如

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

注释必须是有效的 XML 文本。这比 XQuery 更严格。例如，< 和 & 必须表示为 < 和 &