Syntax and Usage

Comments for xqDoc must start with (:~ and end with :). Comments can span multiple lines. New lines do not need to be introduced with a special character. You can use <br/> to force a line break, which you might want to do to aid readability. Comments that start with (: (standard XQuery syntax) are ignored by xqDoc.

The first comment in an XQuery document is interpreted by xqDoc as the Module Description. Within that comment, xqDoc recognizes certain keywords preceded by the at (@) sign. Examples include @author and @version. See the xqDoc documentation at http://www.xqdoc.org for more information. Here is a report for the same document shown in Figure 347 with a user-defined module and function descriptions.

Figure 348. xqDoc Report with Additional Module and Function Descriptions

All other comments must precede function declarations. xqDoc uses the text you enter to provide a description for each function listed in the Function Summary. The same description is used in the Function Detail. Here is an illustration of the XQuery document in the XQuery Editor; the xqDoc comments are highlighted:

Figure 349. xqDoc Comments as Seen in XQuery Source

Save the XQuery Document

When you annotate an XQuery document using xqDoc comments, make sure to save the XQuery document before generating documentation. Unsaved work is not detected by the report generating mechanism.

ActiveX Controls

xqDoc reports use ActiveX controls for navigation and code sample generation. Make sure to enable ActiveX controls for the browser displaying the xqDoc report.