Comments may appear at the beginning or end of an input document, or within element content. Example 21-1 shows a small XML document with two comments, on the second and fifth lines.

<?xml version="1.0" encoding="UTF-8"?>
<!-- This is a business document -->
<b:businessDocument xmlns:b="http://datypic.com/b">
  <b:header>
     <!-- date created --><b:date>2006-10-15</b:date>
  </b:header>
</b:businessDocument>

Comment nodes do not have any children, and their parent is either a document node or an element node. In this example, the comment on the second line is a child of the document node, and the comment on the fifth line is a child of the b:header element.

Comment nodes do not have names, so calling any of the name-related functions with a comment node will result in the empty sequence or a zero-length string, depending on the function. The string value (and typed value) of a comment node is its content, as an instance of xs:string.

Comments can be queried using path expressions. The comment( ) kind test can be used to specifically ask for comments. For example:

doc("comment.xml")//comment( )

will return both comments in the document, while:

doc("comment.xml")/b:businessDocument/b:header/comment( )

will return only the second comment.

The node( ) kind test will return comments as well as all other node kinds. For example:

doc("comment.xml")/b:businessDocument/b:header/node( )

will return a sequence consisting of the second comment, followed by the b:date element. This is in contrast to *, which selects child element nodes only.

You can take the string value of a comment node (e.g., using the string function) and use that string in various operations.

The comment( ) keyword can also be used in sequence types to match comment nodes. For example, if you wanted to write a function that places the content of a comment in a constructed comment element, you could use the function shown in Example 21-2. The use of the comment( ) sequence type in the function signature ensures that only comment nodes are passed to this function.

declare function local:createCommentElement
  ($commentToAdd as comment()) as element( ) {
  <comment>{string($commentToAdd)}</comment>
};

A comment node will also match the node( ) and item( ) sequence types.

XML comment constructors can be used in queries to specify XML comments. Unlike XQuery comments, which are delimited by (: and :), XML comments are intended to appear in the results of the query.

XML comments can be constructed using either direct or computed constructors. A direct XML comment constructor is delimited as it would be in an XML document, by <!-- and -->. It is included character by character in the results of the query; no expressions that appear in direct comment constructors are evaluated.

Computed comment constructors are useful when you want to calculate the value of a comment. A computed comment constructor consists of an expression surrounded by comment{ and }, as shown in Figure 21-1. The expression within the constructor is evaluated and cast to xs:string.

Figure 21-1. Syntax of a computed comment constructor

As in XML syntax, neither direct nor computed comment constructors can result in a comment that contains two consecutive hyphens (--) or ends in a hyphen.

Example 21-3 shows examples of XML comment constructors. As you can see, the enclosed expression in the direct constructor is not evaluated, while the expression in the computed constructor is evaluated. In either case, a comment constructor results in a standard XML comment appearing in the query results.

Query
let $count := count(doc("catalog.xml")//product)
(: unordered list :)
return <ul>
         <!-- {concat(" List of ", $count, " products ")} -->
         {comment{concat(" List of ", $count, " products ")}}
       </ul>
Results
<ul>
  <!-- {concat(" List of ", $count, " products ")} -->
  <!-- List of 4 products -->
</ul>

Note that the XQuery comment (: unordered list :) is not included in the results. XQuery comments, described in Chapter 3, are used to comment on the query itself.