Difference between revisions of "Inspection Module"
Line 70: | Line 70: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Retrieves the string from the specified {{Code|$input}}, parses it as XQuery module, and generates an xqDoc element.<br/>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 and variable and function declarations. We have slightly | + | |Retrieves the string from the specified {{Code|$input}}, parses it as XQuery module, and generates an xqDoc element.<br/>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 and variable and function declarations.<br/> |
− | * an {{Code|<xqdoc: | + | We have slightly updated the [http://files.basex.org/etc/xqdoc-1.1.30052013.xsd xqDoc schema] to do justice to the current status of XQuery:<br/> |
− | * | + | * an {{Code|<xqdoc:annotations/>}} node is added to each variable or function when it uses annotations |
− | * | + | * a single {{Code|<xqdoc:namespaces/>}} node is added to the root element, which summarizes all prefixes used or declared in the module |
+ | * name and type elements are added to variables | ||
|- | |- | ||
| '''Errors''' | | '''Errors''' |
Revision as of 16:03, 1 June 2013
This XQuery Module contains functions for extracting internal information about modules and functions and generating documentation.
Contents
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"> <argument 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 <function name="local:same" uri="http://www.w3.org/2005/xquery-local-functions"> <argument type="xs:integer" name="number">number to return</argument> <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:module
Signatures | inspect:module($uri as xs:string) as element(module)
|
Summary | Retrieves the string from the specified $input , parses it as XQuery module, and generates an element that dscribes its structure.
|
Errors | FODC0002 : the addressed resource cannot be retrieved.
|
Examples | An example is shown below. |
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 updated the xqDoc schema to do justice to the current status of XQuery:
|
Errors | FODC0002 : the addressed resource cannot be retrieved.
|
Examples | 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"> <argument name="number" type="xs:integer">number to return</argument> <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.