Commenting XML Schemas

You can apply comments to your XML Schema documents in a couple of ways. The first is fairly simple and straightforward-using standard XML comments.

Standard XML Comments

Because this is an XML document, you can place comments in the XML Schema document just as you can in any other XML or HTML document. Comments are placed between the <!-- and the --> character sets. An example of commenting your schema document using this method is presented in Listing 6-48.

Listing 6-48: Commenting XML Schema documents

      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>      <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">        <!-- Schema created by Bill Evjen in the summer of 2006 -->        <xs:element name="Process">          <xs:complexType>            <xs:sequence>              <xs:element name="Name" type="xs:string" />              <xs:element name="Address" type="xs:string" />              <xs:element name="City" type="xs:string" />              <xs:element name="State" type="xs:string" />              <xs:element name="Country" type="xs:string" />            </xs:sequence>          </xs:complexType>        </xs:element>      </xs:schema> 

You can also comment out entire blocks of text or code by putting the comment elements on multiple lines as is presented in Listing 6-49.

Listing 6-49: Commenting XML Schema documents in blocks

      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>      <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">        <xs:element name="Process">          <xs:complexType>            <xs:sequence>              <xs:element name="Name" type="xs:string" />              <xs:element name="Address" type="xs:string" />              <xs:element name="City" type="xs:string" />              <!-- Turned off for now              <xs:element name="State" type="xs:string" />              <xs:element name="Country" type="xs:string" /> -->            </xs:sequence>          </xs:complexType>        </xs:element>      </xs:schema> 

From this, you can see that the <State> and <Country> elements have been commented out and will no longer be recognized by any engine.

<annotation>

A child element of the <element> element is the <annotation> element. The <annotation> element allows you to add comments to your schema documents more professionally. The <annotation> element has a couple of child elements at its disposal-<documentation> and <appInfo>.

<documentation>

The <documentation> element allows you to write textual documentation concerning a specific element. An example of its use is presented in Listing 6-50.

Listing 6-50: Using the <documentation> element

      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>      <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">        <xs:element name="Process">          <xs:complexType>            <xs:sequence>               <xs:element name="Name" type="xs:string">                  <xs:annotation>                    <xs:documentation>This represents the full name of the                     person making the order (e.g. John Doe).                    </xs:documentation>                  </xs:annotation>              </xs:element>              <xs:element name="Address" type="xs:string" />              <xs:element name="City" type="xs:string" />              <xs:element name="State" type="xs:string" />              <xs:element name="Country" type="xs:string" />            </xs:sequence>          </xs:complexType>        </xs:element>      </xs:schema> 

<appInfo>

The <appInfo> element allows you to stick application-specific documentation in addition to human readable documentation inside the same element.