<xs:annotation>
element that allows you to add descriptions/comments into any XML Schema.
Actually, <xs:annotation> is a container of two other elements:
<xs:appinfo>,
which is supposed for some custom instructions that may be used by a software processing the schema.
<xs:documentation>,
which is where you should insert your description text.
"SalutationType" type using <xs:annotation> element:
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 |
|---|---|
<
| < |
&
| & |
>
| > |
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.
<xs:annotation> element you can look also by these links:
<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.
|
||
| 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». |
||
| 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».
|
||
| In definitions of local elements or global element references |
Here, the <xs:annotation> is a child of one of the local XSD elements:
|
||
| 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.
|
||
| 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».
|
Additionally, processing of all annotations is controlled by the parameter group: Processing | Annotations
<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:
false).