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:
This address is for your typical U.S. addresses
<element name="StreetAddress" type="string"
If multiple lines are needed (i.e. street
address and apartment number), just enter
them all here (i.e. only on node here).
<element name="City" type="string"/>
<element name="State" type="string"/>
<element name="Zip" type="string"/>
<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
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.
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.