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

image from book
      <?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> 
image from book

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

image from book
      <?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> 
image from book

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

image from book
      <?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> 
image from book

<appInfo>

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




Professional XML
Professional XML (Programmer to Programmer)
ISBN: 0471777773
EAN: 2147483647
Year: 2004
Pages: 215

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net