Difference between revisions of "Inspection Module"
Line 30: | Line 30: | ||
=Example= | =Example= | ||
− | The following example module... | + | The query {{Code|xqdoc:parse('sample.xq')}}} will convert the following example module... |
<pre class="brush:xquery"> | <pre class="brush:xquery"> | ||
Line 42: | Line 42: | ||
module namespace samples = 'http://basex.org/modules/samples'; | module namespace samples = 'http://basex.org/modules/samples'; | ||
− | (:~ This is a sample | + | (:~ This is a sample string. :) |
− | declare variable $samples: | + | declare variable $samples:test-string |
+ | as xs:string := 'this is a string'; | ||
(:~ | (:~ | ||
− | : This function simply returns the specified | + | : This function simply returns the specified integer. |
: @param $number number to return | : @param $number number to return | ||
: @return specified number | : @return specified number | ||
:) | :) | ||
− | declare function samples:same($number as xs:integer) as xs:integer { | + | declare %private function samples:same( |
+ | $number as xs:integer | ||
+ | ) as xs:integer { | ||
$number | $number | ||
}; | }; | ||
</pre> | </pre> | ||
− | ... | + | ...to the following output: |
<pre class="brush:xml"> | <pre class="brush:xml"> | ||
<xqdoc:xqdoc xmlns:xqdoc="http://www.xqdoc.org/1.0"> | <xqdoc:xqdoc xmlns:xqdoc="http://www.xqdoc.org/1.0"> | ||
<xqdoc:control> | <xqdoc:control> | ||
− | <xqdoc:date>2013-05- | + | <xqdoc:date>2013-05-31T08:40:09.864+02:00</xqdoc:date> |
<xqdoc:version>1.1</xqdoc:version> | <xqdoc:version>1.1</xqdoc:version> | ||
</xqdoc:control> | </xqdoc:control> | ||
Line 70: | Line 73: | ||
<xqdoc:variables> | <xqdoc:variables> | ||
<xqdoc:variable> | <xqdoc:variable> | ||
− | <xqdoc:name>samples: | + | <xqdoc:name>samples:test-string</xqdoc:name> |
<xqdoc:comment> | <xqdoc:comment> | ||
− | <xqdoc:description>This is a sample | + | <xqdoc:description>This is a sample string.</xqdoc:description> |
</xqdoc:comment> | </xqdoc:comment> | ||
+ | <xqdoc:type>xs:string</xqdoc:type> | ||
</xqdoc:variable> | </xqdoc:variable> | ||
</xqdoc:variables> | </xqdoc:variables> | ||
Line 79: | Line 83: | ||
<xqdoc:function arity="1"> | <xqdoc:function arity="1"> | ||
<xqdoc:comment> | <xqdoc:comment> | ||
− | <xqdoc:description>This function simply returns the specified | + | <xqdoc:description>This function simply returns the specified integer.</xqdoc:description> |
<xqdoc:param>$number number to return</xqdoc:param> | <xqdoc:param>$number number to return</xqdoc:param> | ||
<xqdoc:return>specified number</xqdoc:return> | <xqdoc:return>specified number</xqdoc:return> |
Revision as of 08:40, 31 May 2013
This XQuery Module contains functions for generating xqDoc files from XQuery modules.
Introduction
xqDoc provides a simple vendor neutral solution for generating a documentation from XQuery modules. The documentation conventions have been inspired by the JavaDoc standard. Documentation comments begin with (:~
and end with :)
, and tags start with @
. xqDoc comments can be specified for main and library modules and variable and function declarations. We have slightly extended the conventions and updated the xqDoc schema:
- an
<xqdoc:namespaces/>
node lists all namespaces of a module - if annotations are attached to variables or functions, an
<xqdoc:annotations/>
node is added - variables now have a name and a type.
An example is shown below.
Conventions
All functions in this module are assigned to the http://basex.org/modules/xqdoc
namespace, which is statically bound to the xqdoc
prefix.
All errors are assigned to the http://basex.org/errors
namespace, which is statically bound to the bxerr
prefix.
Functions
xqdoc:parse
Signatures | xqdoc:parse($input as xs:string) as element(xqdoc:xqdoc)
|
Summary | Parses the specified $input and generates an xqDoc element.
|
Example
The query xqdoc:parse('sample.xq')
} will convert the following example module...
(:~ : This module provides some sample functions to demonstrate : the features of the XQDoc Module. : @author BaseX Team : @see http://docs.basex.org/wiki/XQDoc_Module : @version 1.0 :) module namespace samples = 'http://basex.org/modules/samples'; (:~ This is a sample string. :) declare variable $samples:test-string as xs:string := 'this is a string'; (:~ : This function simply returns the specified integer. : @param $number number to return : @return specified number :) declare %private function samples:same( $number as xs:integer ) as xs:integer { $number };
...to the following output:
<xqdoc:xqdoc xmlns:xqdoc="http://www.xqdoc.org/1.0"> <xqdoc:control> <xqdoc:date>2013-05-31T08:40:09.864+02:00</xqdoc:date> <xqdoc:version>1.1</xqdoc:version> </xqdoc:control> <xqdoc:module type="library"> <xqdoc:uri>http://basex.org/modules/samples</xqdoc:uri> <xqdoc:name>sample.xq</xqdoc:name> </xqdoc:module> <xqdoc:imports/> <xqdoc:variables> <xqdoc:variable> <xqdoc:name>samples:test-string</xqdoc:name> <xqdoc:comment> <xqdoc:description>This is a sample string.</xqdoc:description> </xqdoc:comment> <xqdoc:type>xs:string</xqdoc:type> </xqdoc:variable> </xqdoc:variables> <xqdoc:functions> <xqdoc:function arity="1"> <xqdoc:comment> <xqdoc:description>This function simply returns the specified integer.</xqdoc:description> <xqdoc:param>$number number to return</xqdoc:param> <xqdoc:return>specified number</xqdoc:return> </xqdoc:comment> <xqdoc:name>samples:same</xqdoc:name> <xqdoc:signature>declare function samples:same($number as xs:integer) as xs:integer</xqdoc:signature> <xqdoc:parameters> <xqdoc:parameter> <xqdoc:name>number</xqdoc:name> <xqdoc:type>xs:integer</xqdoc:type> </xqdoc:parameter> </xqdoc:parameters> <xqdoc:return> <xqdoc:type>xs:integer</xqdoc:type> </xqdoc:return> </xqdoc:function> </xqdoc:functions> </xqdoc:xqdoc>
Changelog
This module was introduced with Version 7.7.