• Chapter 1: Getting Started with Stylus Studio
• Chapter 2: Editing and Querying XML
• Chapter 3: Converting Non-XML Files to XML
• Chapter 4: Working with XSLT
• Chapter 5: Creating XSLT Using the XSLT Mapper
• Chapter 6: Debugging Stylesheets
• Chapter 7: Defining XML Schemas
  • What Is an XML Schema?
  • Creating an XML Schema in Stylus Studio
  • Working with XML Schema in Stylus Studio
  • Getting Started with XML Schema in the Tree View
  • Defining simpleTypes in XML Schemas
  • Defining complexTypes in XML Schemas
  • Defining Elements and Attributes in XML Schemas
  • Defining Groups of Elements and Attributes in XML Schemas
  • Adding Comments, Annotation, and Documentation Nodes to XML Schemas
    • Comments
    • Annotations
    • Example
  • Defining Notations
  • Referencing External XML Schemas
  • Generating Documentation for XML Schemas
  • About XML Schema Properties
• Chapter 8: Defining Document Type Definitions
• Chapter 9: Writing XPath Expressions
• Chapter 10: Working with XQuery in Stylus Studio
• Chapter 11: Composing Web Service Calls
• Chapter 12: Accessing Relational Data as XML
• Chapter 13: Extending Stylus Studio
• Chapter 14: Stylus Studio GUI Reference

Home > Online Product Documentation > Table of Contents > Adding Comments, Annotation, and Documentation Nodes to XML Schemas

Adding Comments, Annotation, and Documentation Nodes to XML Schemas

The XML Schema Recommendation provides comment and annotation nodes for you to provide information that documents an XML Schema. You can add these nodes to any node in an XML Schema.

The difference between comments and annotations is that a human being must read a comment node for it to have meaning. An annotation element allows you to specify nodes that a stylesheet can operate on.

Comments

You cannot add comments in the Diagram tab.

To add comments in the Tree tab:

2. In the left tool bar, click New Comment . In the Tree view, Stylus Studio displays a field for the comment.

Annotations

You use an annotation element to provide information about the XML Schema. You can annotate any node in your XML Schema. The annotation element always contains at least one appInfo or documentation node. Any text you want to enter must be entered in one of these nodes.

Diagram View

When you create an annotation in the Diagram tab, you create the element and specify its subelement ( appInfo or documentation) in the Diagram tab. You can further describe the node

To add an annotation:

The annotation icon appears in the Diagram tab .

3. Right-click the annotation icon and select the type of annotation you want to define - appInfo ( )or documentation ( ).

Tree View

To add an annotation:

2. In the left tool bar, click New Annotation . Stylus Studio creates and selects an Annotation node.

3. In the left tool bar, click New Documentation or New Application Info .

Double-click the Language field and enter the language of the contents of the source file.

5. In the left tool bar, click New Text . In the Tree view, Stylus Studio displays a field for the new text.

Moving a Comment or Annotation

If the parent of the new comment or annotation node has more than one child, you can move the comment or annotation with the up or down arrow. However, you cannot move the comment or annotation out of the scope of its parent.

Example

In an XML Schema, you might have a comment node such as the following:

<xsd:schema ...>
               

              

                
<!-- The following element is .... -->
                   
<xsd:element name="..."/>
                   

                
              

            

The contents of a comment node have meaning only when a person reads them. However, the contents of annotation nodes can be operated on. For example:

<xsd:schema ... > 
               

              

                
<xsd:element name="foo"> 
                   
<xsd:annotation> 
                   

                
              
<xsd:documentation language="en"> 
               
This is a <b>foo</b> element. Use it for ... 
               
</xsd:documentation> 
               
<xsd:documentation language="jp"> 
               
xksnjgfyre fvhfdbvhjds 
               
</xsd:documentation> 
               

              

                
</xsd:annotation> 
                   
</xsd:element> 
                   
...
                   

                
              

            

You can apply an XSLT stylesheet to this XML Schema document. The stylesheet could generate an HTML manual by extracting the Documentation nodes in the desired language:

<xsl:stylesheet ... > 
               

              

                
<xsl:template match="xsd:element"> 
                   
<xsl:apply-templates select=
                   

                
              
"xsd:annotation/xsd:documentation[@language='en']"/> 
               

              

                
</xsl:template> 
                   
...