5.4 Adding Documentation

Both the readers of your XML schema and the users of the generated Java classes will be more than grateful for each morsel of documentation. JAXB does a good job by providing most if not all of the Javadoc that can be generated automatically. While this is good at describing the relation between the generated Java code and the originating chunks of the XML schema, it conveys nothing about the intentions behind the schema itself.

Documentation is probably best written inline, as part of the type definition in your schema. This way it remains close to the schema text it refers to and documents (not quite perfectly) the XML schema itself. Here is one way of adding some documentation for a class derived from a complex type definition:

<xsd:complexType name="GlobalType">
  <xsd:annotation>
    <xsd:appinfo>
      <jxb:class>
        <jxb:javadoc>
A &lt;code>GlobalType&lt;/code> object represents a single defglobal
variable definition. The variable name must begin and end with an
asterisk ('*').
        </jxb:javadoc>
      </jxb:class>
    </xsd:appinfo>
  </xsd:annotation>
  <xsd:complexContent>
    <xsd:extension base="AssignmentType"/>
  </xsd:complexContent>
</xsd:complexType>

Notice that any XML markup requires the escaping of all less-than and ampersand characters, i.e., "<" and "&" must be written as "<" and "&". (Another possibility is writing the text as a CDATA section, see below.) The text is added up front to the Javadoc text JAXB will provide anyway. Your browser will show you this text as the head of the documentation for the class GlobalType:

public class GlobalType
extends AssignmentType

A GlobalType object represents a single defglobal variable definition. The variable name must begin and end with an asterisk ('*').

Java class for GlobalType complex type.
...

Documentation for elements and attributes is added in a similar manner. For either of these schema components, you add a child as shown in the example below.

<xsd:element name="elemA" type="xsd:string">
  <xsd:annotation>
    <xsd:appinfo>
      <jxb:property>
        <jxb:javadoc>
This documents a property which happens to be an
XML Schema element.
        </jxb:javadoc>
      </jxb:property>
    </xsd:appinfo>
  </xsd:annotation>
</xsd:element>

Finally, we'll look at a snippet as it might be included to appear as package level documentation. It can be written at the outermost level of the schema.

<xsd:schema>
...
<xsd:annotation>
  <xsd:appinfo>
    <jxb:schemaBindings>
      <jxb:package name="com.jessrules.jessml">
        <jxb:javadoc>
<![CDATA[<body>This package contains classes derived from the XML
schema JessML2_0. They represent XML element content for Jess constructs
and function calls, including their subordinate elements. Two documents
are supported:
<ol>
  <li>rulebase documents containing Jess constructs and function calls
  <li>fact-list documents containing the result of a call to
      <code>save-facts-xml</code>
</ol>
</body>]]>
        </jxb:javadoc>
      </jxb:package>
    </jxb:schemaBindings>
  </xsd:appinfo>
</xsd:annotation>

This example features the XML technique for including arbitrary content as a CDATA section. It enables you to write HTML tags in a more readable way.

table of contents