Chapter 5: XML Documentation and xmlDraft

One of the benefits of XML Schemas is the built in methods of documentation. XML Schemas handles documentation through their <annotation> node, and have two methods for documentation, one for user-readability aptly called <documentation> and one intended to be an open-ended way for vendors to add specific information called <appinfo>. xmlDraft focuses on the <documentation> node and has an easy way of adding documentation to a schema.

<annotation> node in XML Schema

The <annotation> node is XML Schema's built in support for documentation. This node can be a child of practically every schema node, in effect allowing the schema to be documented as deeply and as detailed as necessary. <annotation> itself does not allow for any text, rather it has two child nodes that do: <documentation> and <appinfo>.

<documentation> is used to give user-friendly documentation about the node that is being annotated. For example, if the name of the node is not explicit enough, or if for some business purpose this node in usage is given a different value than what it was originally intended, it's best to document that information somewhere. The schema is the best place to put this documentation.

Below is an example of how to use the <documentation> node inside of a schema:

<element name="Address"> <annotation> <documentation> This address is for your typical U.S. addresses </documentation> </annotation> <complexType> <sequence> <element name="StreetAddress" type="string" minOccurs="1" maxOccurs="3"> <annotation> <documentation> If multiple lines are needed (i.e. street address and apartment number), just enter them all here (i.e. only on node here). </documentation> </annotation> </element> <element name="City" type="string"/> <element name="State" type="string"/> <element name="Zip" type="string"/> </sequence> </complexType> </element>

<appinfo> is meant as an open-ended way for applications and parsers to add custom-specific nodes to schemas, and since this document is focusing on how schemas can be documented for the user, and not for any specific parser, we will not discuss that node.

Documentation made easy with xmlDraft

XML Schema documentation in the Instance Tree

Documentation could not be easier than inside xmlDraft. As has been noted above, each node of the instance document is represented inside a visual tree. Here, you can display relevant properties of those nodes, and one of them is Documentation. If you have the documentation column displayed, adding documentation to nodes is a snap. Simply type in your documentation, hit return, and arrow-down to the next node to document.

If you have the need for fairly in-depth documentation, clicking on the elipsis (or hitting alt+enter) button will bring up a resizable dialog to enter in your text.

XML Schema documentation in the Property Window

And lastly, the Properties window also has a Documentation row that can be edited, along with an ellipsis button to bring up the same text dialog for lengthy documentation.

<- Return

Continue ->