xqDoc

(1Q18)


xqDoc comments (see xqdoc.org) are used to document XQuery library and main modules in a manner similar to how Javadoc comments are used to document Java classes and packages. With the documentation close to the source, documentation maintenance is easier. From this, xqDoc can generate useful documentation quickly and easily.

An XQuery module does not need to contain xqDoc style comments in order for the xqDoc tools to produce useful output. Even without any xqDoc documentation style comments, a cross reference (for modules, functions, and variables) and XQuery code browser (for modules and functions) will be created by xqDoc.

xqDoc comments are extracted when eXist-db parses an XQuery. It keeps them with the function signature.

To speed up parsing, xqDoc uses "lazy evaluation". Comments are stored as plain strings first. This is parsed and merged into the function signature when needed. It allows tools like eXide to display up to date documentation while working on a module.

Comment Style

xqDoc style comments begin with (:~  and end with  :).

An xqDoc style comment can be specified for each of the following:

Library Modules:

  • Module Declaration

  • Module Import

  • Variable Definition

  • Function Definition

Main Modules:

  • Main Module

  • Module Import

  • Variable Definition

  • Function Definition

An xqDoc comment contains specials strings, called tags Tags start with an @ character. The text up to the first tag is assumed to be the general description for the component being documented.

The following tags are recognized and handled:

@author

Author of this component. Occurrences: zero or more.

(:~
@author Darin McBeath
:)
@version

Version of the component. Occurrences: zero or more, but only a single @version makes sense.

(:~
@version 1.0
:)
@since

Identifies the version of the module since when this component is supported. Occurrences: zero or more, but only a single @since makes sense.

@see

Adds a hypertext link to an external site, a library or main module, a specific function or variable, or arbitrary text. Occurrences: zero or more.

  • To link to an external site, use a complete URL such as http://www.xquery.com.

  • To link to a library or main module (contained in xqDoc), provide the URI for this (see example below).

  • To link to a specific function or variable (contained in xqDoc), provide the URI for the library or main module, followed by a semicolon ; and the function or variable name.

  • To provide a name for a link, add a semicolon ;, followed by the name

  • Anything else will be interpreted as just text.

(:~
@see http://www.xquery.com
@see xqdoc/xqdoc-display
@see xqdoc/xqdoc-display;build-link
@see xqdoc/xqdoc-display;$months
@see xqdoc/xqdoc-display;$months;month variable
@see http://www.xquery.com;;xquery
@see some text
:)
@param

Describes the parameters associated with a function. Append the parameter name and its description.

(:~
@param $name The username
:)
@return

Describes the return value from a function. Occurrences: zero or more.

(:~
@return Sequence of names matching the search criteria
:)
@deprecated

Identifies the component as deprecated. Its text should indicate the reason and its optional replacement.

@error

Identifies an error raised by the function. Occurrences: zero or more.

(:~
@error The requested URI does not exist
:)

Values provided for each of the tags can contain embedded XHTML markup to enhance or emphasize the xqDoc presentation. However, make sure the content is well formed and that entities are used (for instance & instead of &).

Examples

Two examples for library and function comments.

Library module comment:

(:~ 
 : This module provides the functions that control the Web presentation
 : of xqDoc. The logic contained in this module is not specific to any
 : XQuery implementation and is written to the May 2003 XQuery working
 : draft specification. It would be a trivial exercise to convert this
 : code to either the Nov 2003 or Oct 2004 XQuery working draft.
 :
 : It should also be noted that these functions not only support the 
 : real-time presentation of the xqDoc information but are also used
 : for the static offline presentation mode as well. The static offline
 : presentation mode has advantages because access to a native XML
 : database is not needed when viewing the xqDoc information ... it is
 : only needed when generating the offline materials. 
 :
 : @author Darin McBeath
 : @version 1.0
 :)
module "xqdoc/display"

Function comment

(:~ 
 : The controller for constructing the xqDoc HTML information for
 : the specified library module. The following information for
 : each library module will be generated.
 : <ul>
 : <li> Module introductory information</li>
 : <li> Global variables declared in this module</li>
 : <li> Modules imported by this module</li>
 : <li> Summary information for each function defined in the module</li>
 : <li> Detailed information for each function defined in the module</li>
 : </ul>
 :
 : @param $uri the URI for the library module
 : @param $local indicates whether to build static HTML link for offline
 : viewing or dynamic links for real-time viewing.
 : @return XHTML.
 :)
define function print-module($uri as xs:string, $local as xs:boolean) as element()*