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 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 337 with a user-defined module and function descriptions.

Figure 338. 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 in the XQuery Editor; the xqDoc comments are highlighted:

Figure 339. xqDoc Comments as Seen in XQuery Source

Save the XQuery

When you annotate an XQuery using xqDoc comments, make sure to save the XQuery 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.