Difference between revisions of "Inspection Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 3: Line 3:
 
=Introduction=
 
=Introduction=
  
−
[http://xqdoc.org 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 {{Code|(:~}} and end with {{Code|:)}}, and tags start with {{Code|@}}. xqDoc comments can be specified for main and library modules, variable declarations and function declarations, as shown in the following example:
+
[http://xqdoc.org 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 {{Code|(:~}} and end with {{Code|:)}}, and tags start with {{Code|@}}. xqDoc comments can be specified for main and library modules, variable declarations and function declarations, as shown in the [[Example|example]] below.
 +
 
 +
=Conventions=
 +
 
 +
All functions in this module are assigned to the {{Code|http://basex.org/modules/xqdoc}} namespace, which is statically bound to the {{Code|xqdoc}} prefix.<br/>
 +
All errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.
 +
 
 +
=Functions=
 +
 
 +
==xqdoc:parse==
 +
{| width='100%'
 +
|-
 +
| width='90' | '''Signatures'''
 +
|{{Func|xqdoc:parse|$input as xs:string|element(xqdoc:xqdoc)}}
 +
|-
 +
| '''Summary'''
 +
|Parses the specified {{Code|$input}} and generates an xqDoc element.
 +
|}
 +
 
 +
=Example=
 +
 
 +
The following example module...
  
 
<pre class="brush:xquery">
 
<pre class="brush:xquery">
Line 26: Line 47:
 
   $number
 
   $number
 
};
 
};
−
 
 
</pre>
 
</pre>
  
−
=Conventions=
+
...will be converted to the following xqDoc file:
  
−
All functions in this module are assigned to the {{Code|http://basex.org/modules/xqdoc}} namespace, which is statically bound to the {{Code|xqdoc}} prefix.<br/>
+
<pre class="brush:xml">
−
All errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.
+
<xqdoc:xqdoc xmlns:xqdoc="http://www.xqdoc.org/1.0">
−
 
+
  <xqdoc:control>
−
=Functions=
+
    <xqdoc:date>2013-05-31T00:13:02.199+02:00</xqdoc:date>
−
 
+
    <xqdoc:version>1.1</xqdoc:version>
−
==xqdoc:parse==
+
  </xqdoc:control>
−
{| width='100%'
+
  <xqdoc:module type="library">
−
|-
+
    <xqdoc:uri>http://basex.org/modules/samples</xqdoc:uri>
−
| width='90' | '''Signatures'''
+
    <xqdoc:name>sample.xq</xqdoc:name>
−
|{{Func|xqdoc:parse|$input as xs:string|element(xqdoc:xqdoc)}}
+
  </xqdoc:module>
−
|-
+
  <xqdoc:imports/>
−
| '''Summary'''
+
  <xqdoc:variables>
−
|Parses the specified {{Code|$input}} and generates an xqDoc element.
+
    <xqdoc:variable>
−
|}
+
      <xqdoc:name>samples:number</xqdoc:name>
 +
      <xqdoc:comment>
 +
        <xqdoc:description>This is a sample number.</xqdoc:description>
 +
      </xqdoc:comment>
 +
    </xqdoc:variable>
 +
  </xqdoc:variables>
 +
  <xqdoc:functions>
 +
    <xqdoc:function arity="1">
 +
      <xqdoc:comment>
 +
        <xqdoc:description>This function simply returns the specified number.</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>
 +
</pre>
  
 
=Changelog=
 
=Changelog=

Revision as of 00:14, 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, variable declarations and function declarations, as shown in the example 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 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 number. :)
declare variable $samples:number := 1;

(:~
 : This function simply returns the specified number.
 : @param $number number to return
 : @return specified number
 :)
declare function samples:same($number as xs:integer) as xs:integer {
  $number
};

...will be converted to the following xqDoc file: 

<xqdoc:xqdoc xmlns:xqdoc="http://www.xqdoc.org/1.0">
  <xqdoc:control>
    <xqdoc:date>2013-05-31T00:13:02.199+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:number</xqdoc:name>
      <xqdoc:comment>
        <xqdoc:description>This is a sample number.</xqdoc:description>
      </xqdoc:comment>
    </xqdoc:variable>
  </xqdoc:variables>
  <xqdoc:functions>
    <xqdoc:function arity="1">
      <xqdoc:comment>
        <xqdoc:description>This function simply returns the specified number.</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.

Retrieved from "http://docs.basex.org/index.php?title=Inspection_Module&oldid=9375"