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 更嚴格。例如，< 和 & 必須表示為 < 和 &