xqDoc
Introduction
xqDoc comments 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, it increases the chances that the documentation will be kept current and with tools provided by xqDoc, useful documentation can be quickly and easily generated. It should be noted that a XQuery module does not need to contain xqDoc style comments in order for the xqDoc tools to produce useful output. Without any xqDoc documentation style comments, a very useful cross reference (for modules, functions, and variables) and XQuery code browser (for modules and functions) will be created by the xqDoc tools.
xqDoc comments are extracted when eXist parses an XQuery and keeps them with the FunctionSignature. To not slow down the parsing, comments are stored as plain strings. The comments can be parsed and merged into the function signature later, if they are needed. This would allow tools like eXide to display up to date documentation while you are working on a module.
Comment Style
xqDoc style comments begin with a '(:~' and end with a ':)' . Of course, '(::' would have been preferable to indicate the beginning of an xqDoc style comment (since it mimics the JavaDoc style of '/**' ) but we didn't want to cause confusion with an XQuery pragma (since this decision was made, the definition for XQuery pragma has been changed). The choice for the begin pattern is really quite arbitrary. In any case, one xqDoc style comment can be specified before each of the following rules (based on the W3C XQuery 1.0 BNF) for library modules and main modules.
Library Modules
-
Module Declaration
-
Module Import
-
Variable Definition
-
Function Definition
Main Modules
-
Main Module
-
Module Import
-
Variable Definition
-
Function Definition
Like Javadoc, the following tags have special meaning within an xqDoc comment. In addition, the values provided for each of the tags can contain embedded XHTML markup to enhance or emphasize the xqDoc XHTML presentation. However, make sure the content is well formed and that entities are used (i.e. & instead of &). The beginning text (up to the first tag) is assumed to be description text for the component being documented.
@author
The @author tag identifies the author for the documented component. Zero or more @author tags can be specified (one per author)
@version
The @version tag identifies the version of the documented component. Zero or more @version tags can be specified (one per version) but in reality only a single @version tag would normally make sense. The value for the @version tag can be an arbitrary string.
@since
The @since tag identifies the version when a documented component was supported. Zero or many @since tags can be specified, but in reality only a single @since tag would normally make sense. The value for the @since tag can be an arbitrary string but should likely match an appropriate version value.
@see
The @see tag provides the ability to hypertext link to an external web site, a library or main module contained in xqDoc, a specific function (or variable) defined in a library or main module contained in xqDoc, or arbitrary text. 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, simply provide the URI for the library or main module. To link to a specific function (or variable) defined in an xqDoc library or main module, simply provide the URI for the library or main module followed by a ';' and finally the function or variable name. To provide a name for a link, simply include a second ';' followed by the name. To provide text, simply include the 'text'. Multiple @see tags can be specified (one per link or string of text).
@param
The @param tag identifies the parameters associated with a function. For each parameter in a function, there should be a @param tag. The @param tag should be followed by the parameter name (as indicated in the function signature) and then the parameter description.
@return
The @return tag describes what is returned from a function. Zero or one @return tags can be specified.
@deprecated
The @deprecated tag identifies the identifies the documented component as being deprecated. The string of text associated with the @deprecated tag should indicate when the item was deprecated and what to use as a replacement.
@error
The @error tag identifies the types of errors that can be generated by the function. Zero or more @error tags can be specified. An arbitrary string of text can be provided for a value.
A representative library module comment
This comment would precede the module declaration statement for the library module.
A representative library module function comment
This comment would precede the function declaration statement in the library module.