FlexDoc/XML - XSDDoc - FAQ

Working with annotations

How to add descriptions/comments into XML schema?

The W3C XML Schema language defines a special <xs:annotation> element that allows you to add descriptions/comments into any XML Schema.

Actually, <xs:annotation> is a container of two other elements:

  1. <xs:appinfo>, which is supposed for some custom instructions that may be used by a software processing the schema.
  2. <xs:documentation>, which is where you should insert your description text.
In the following example, the string "Complete List of all Salutations" is the description added in the definition of the "SalutationType" type using <xs:annotation> element:

<xs:simpleType name="SalutationType">
<xs:annotation>
<xs:documentation>Complete List of all Salutations</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:string">
<xs:enumeration value="MR."/>
<xs:enumeration value="MS."/>
<xs:enumeration value="MRS"/>
</xs:restriction>
</xs:simpleType>

Inside <xs:documentation> element you can place any text containing any number of lines. Note also that some XML markup character must be encoded with the corresponding entities:

Character Entity
< &lt;
& &amp; 
> &gt;

Along with the text, you can insert also other XML elements from various namespaces. Particularly important are XHTML elements, which allow you to enrich your annotations with very sophisticated formatting and images that will appear in the generated documentation. For more details, please see: Formatting annotations with XHTML.

For additional information about <xs:annotation> element you can look also by these links:

Which annotations get into generated documentation?

Although <xs:annotation> elements can be inserted in almost any other XML Schema elements, XSDDoc currently processes only those specified at the following locations:

Location Details
In definition of the entire XML schema Here, the <xs:annotation> elements may appear as one or multiple children of the <xs:schema> element. When processed, the annotation text will get into the «Annotation» section of the «Schema Overview». Multiple <xs:annotation> elements will produce separate «Annotation» sub-sections.

Related Parameter:

In definitions of global components Here, the <xs:annotation> element may be a child of one of the XSD elements defining the component:

That will produce the «Annotation» section of the «Component Documentation».

Related Parameter:

In definitions of anonymous Simple/Complex Types of elements/attributes Here, the <xs:annotation> element may be a child of one of the locally used XSD elements: Such an <xs:annotation> is processed into the «Annotation» section of the «Anonymous Type Detail».

Related Parameters:

In definitions of local elements or global element references Here, the <xs:annotation> is a child of one of the local XSD elements: This annotation will appear in the corresponding item of the «Content Element Detail» of the parent component.

In case of globally documented local elements, it will also appear in the «Annotation» section of «Element Documentation».

Related Parameters:

In definitions of local attributes or global attribute references Here, the <xs:annotation> is a child of the locally used XSD element: This annotation will appear in the corresponding item of the «Attribute Detail» of the parent component.

Related Parameter:

In facet definitions Here, the <xs:annotation> may be a child of one of the XSD facet elements:

This annotation will appear in the corresponding «Facet Documentation».

Related Parameters:

Additionally, processing of all annotations is controlled by the parameter group: Descriptions

How to enable/disable interpreting line breaks in comments?

The text enclosed in a <xs:documentation> element may contain any number of lines. You may create the new lines simply for convenience during writing that text. However, you may also use the new lines as a way to format your comments. In that case, you will likely want to have your text broken into the same lines in the «Annotation» sections of the generated documentation. Click on the following screenshot to see how it may look:

That means that the generator must interpret the line breaks found in the raw XML with the markup coding appropriate to the given output format (e.g. with <br> in HTML or \line in RTF).

To tell the generator to do so, you should invoke the output Format Option Inspector (by clicking the «Options» button in the Generator Dialog) and check the option:

If you actually do not need to have the line breaks interpreted (which may be exactly the case when you format your annotation with XHTML), make sure that those options are unchecked (false).

Using HTML markup in annotations

The descriptions specified in <xs:documentation> elements may be preformatted with HTML tags, which can be used in the generated documentation.

There are three ways how you can use HTML in your XSD annotations:

  1. XHTML elements
  2. HTML-like elements
  3. Escaping HTML markup

XHTML elements

Since, XSD files are XML files, you can specify all the HTML formatting in the form of XML tags (elements). That would be XHTML tags.
XHTML is an XML adaptation of HTML. Note that all XHTML elements must belong to the namespace:
http://www.w3.org/1999/xhtml
Example:
<xs:documentation xmlns="http://www.w3.org/1999/xhtml">
  <h3>Complete List of all Salutations</h3>
  Only three forms allowed:
  <ol>
    <li>MR.</li>
    <li>MS.</li>
    <li>MRS</li>
  </ol>
</xs:documentation>
Here, the XHTML tags are highlighted with the red and the specifying of the XHTML namespace for them is highlighted with the green.

Such an annotation can be rendered in the generated documentation as follows:

Complete List of all Salutations

Only three forms allowed:
  1. MR.
  2. MS.
  3. MRS
To have such a markup processed/rendered, make sure the following XSDDoc parameters and format options are specified: For further details, please see: Formatting annotations with XHTML

HTML-like elements

Another possibility is that you define your HTML markup in the form of XML elements, however without XHTML namespace (i.e. in no-namespace). So, you have something looking like XHTML but not exactly it.

Example:

<xs:documentation>
  <h3>Complete List of all Salutations</h3>
  Only three forms allowed:
  <ol>
    <li>MR.</li>
    <li>MS.</li>
    <li>MRS</li>
  </ol>
</xs:documentation>
Processing of that is enabled by the following settings:

Escaping HTML markup

At last, you can use no XML elements at all to express your HTML markup. Instead you specify the HTML tags directly within the text by escaping XML special characters using XML entities.
That's the worst case and we highly discourage using such formatting. However, some XML schemas authors do use it. So, XSDDoc supports that as well.
Example:
<xs:documentation>
  &lt;h3&gt;Complete List of all Salutations&lt;/h3&gt;
  Only three forms allowed:
  &lt;ol&gt;
    &lt;li&gt;MR.&lt;/li&gt;
    &lt;li&gt;MS.&lt;/li&gt;
    &lt;li&gt;MRS&lt;/li&gt;
  &lt;/ol&gt;
</xs:documentation>
Such things can be processed/rendered as well. That can be achieved by the following settings: