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 371 with a user-defined 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:

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.

Viewing Code Samples

You can view code samples from an xqDoc report by clicking the view code hyperlink, as shown in the following illustration.

The XQuery code sample appears in a separate Web browser.

 
Free Stylus Studio XML Training:
W3C Member