Difference between revisions of "Inspection Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 104: Line 104:
 
<module prefix="samples" uri="http://basex.org/modules/samples">
 
<module prefix="samples" uri="http://basex.org/modules/samples">
 
   <variable name="samples:test-string" uri="http://basex.org/modules/samples" type="xs:string">
 
   <variable name="samples:test-string" uri="http://basex.org/modules/samples" type="xs:string">
     <comment>
+
     <description>This is a sample string.</description>
      <description>This is a sample string.</description>
 
    </comment>
 
 
   </variable>
 
   </variable>
 
   <function name="samples:same" uri="http://basex.org/modules/samples">
 
   <function name="samples:same" uri="http://basex.org/modules/samples">
Line 112: Line 110:
 
     <annotation name="private" uri="http://www.w3.org/2012/xquery"/>
 
     <annotation name="private" uri="http://www.w3.org/2012/xquery"/>
 
     <description>This function simply returns the specified integer.</description>
 
     <description>This function simply returns the specified integer.</description>
    <return>specified number</return>
 
 
     <return type="xs:integer">specified number</return>
 
     <return type="xs:integer">specified number</return>
 
   </function>
 
   </function>

Revision as of 14:19, 31 May 2013

This XQuery Module contains functions for extracting internal information about modules and functions and generating documentation.

Conventions

All functions in this module are assigned to the http://basex.org/modules/inspect namespace, which is statically bound to the inspect prefix.
All errors are assigned to the http://basex.org/errors namespace, which is statically bound to the bxerr prefix.

Functions

inspect:function

Signatures inspect:function($function as function()) as element(function)
Summary Inspects the specified $function and returns an element that describs its structure. The output of this function is similar to eXist-db’s inspect:inspect-function function.
Examples The query inspect:function(count#1) yields:
<function name="count" uri="http://www.w3.org/2005/xpath-functions">
  <parameter type="item()" occurrence="*"/>
  <return type="xs:integer"/>
</function>

The function…

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

…is represented by inspect:function(local:same#1) as…

<function name="local:same" uri="http://www.w3.org/2005/xquery-local-functions">
  <parameter type="xs:integer" name="number">number to return</parameter>
  <annotation name="private" uri="http://www.w3.org/2012/xquery"/>
  <description>This function simply returns the specified integer.</description>
  <return type="xs:integer">specified number</return>
</function>

inspect:xqdoc

Signatures inspect:xqdoc($uri as xs:string) as element(xqdoc:xqdoc)
Summary Retrieves the string from the specified $input, parses it as XQuery module, and generates an xqDoc element.
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.
Errors FODC0002: the addressed resource cannot be retrieved.
Example An example is shown below.

Example

This is the sample.xqm library module:

(:~ 
 : This module provides some sample functions to demonstrate
 : the features of the Inspection 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
};

If inspect:module('sample.xqm') is run, the following output will be generated:

<module prefix="samples" uri="http://basex.org/modules/samples">
  <variable name="samples:test-string" uri="http://basex.org/modules/samples" type="xs:string">
    <description>This is a sample string.</description>
  </variable>
  <function name="samples:same" uri="http://basex.org/modules/samples">
    <parameter name="number" type="xs:integer">number to return</parameter>
    <annotation name="private" uri="http://www.w3.org/2012/xquery"/>
    <description>This function simply returns the specified integer.</description>
    <return type="xs:integer">specified number</return>
  </function>
</module>

The output looks as follows if inspect:xqdoc('sample.xqm') is called:

<xqdoc:xqdoc xmlns:xqdoc="http://www.xqdoc.org/1.0">
  <xqdoc:control>
    <xqdoc:date>2013-05-31T08:43:05.123+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.xqm</xqdoc:name>
  </xqdoc:module>
  <xqdoc:imports/>
  <xqdoc:namespaces>
    <xqdoc:namespace prefix="samples" uri="http://basex.org/modules/samples"/>
  </xqdoc:namespaces>
  <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:annotations>
        <xqdoc:annotation name="private"/>
      </xqdoc:annotations>
      <xqdoc:signature>declare %private 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.