Products         Downloads         Licensing         Shop         Customers         User Forum    

 DocFlex Technology
Overview
Features
Documentation
 DocFlex/XML
Overview
Features
Documentation
XSDDoc
Features
Organization
Examples
Templates
FAQ
WSDLDoc
Integrations
Bundles
 DocFlex/Javadoc
Overview
Documentation
Basic Templates
JavadocPro
Examples
Tutorials
 DocFlex/Together
Overview
Examples
Basic Templates
Documentation
Tutorials
 Try
Downloads
Registration
Trial License
 Buy
Licensing
Shop
 Company
News
Products
Customers
About Us
Imprint
Legal
Contact
Links
 

DocFlex/XML - XSDDoc - Features (How everything is documented)

  1. XML Schemas
  2. Namespaces
  3. Components
  4. XML Source
  5. Annotations
  6. Simple Content
  7. Complex Content
  8. Types
  9. Global Elements
  10. Local Elements
  11. Attributes
  12. Global Groups

1.  XML Schemas

Schema Overview

For each XML schema (XSD file) a separate Schema Overview block/page can be generated, which provides the detailed information about the XML schema file as a whole. This may include the following sections:
  1. Schema Profile

    The general summary information about the schema.

    For more details, see XML Schemas | Schema Profile.

  2. Annotation

    This section displays the full annotation text obtained from all <xs:documentation> elements found by the following path:

    xs:schema/xs:annotation/xs:documentation
    Multiple <xs:documentation> elements produce separate sections of the annotation text.

    See also: Annotations

  3. Component Summaries

    The summary tables of all global components and local elements defined in the given XML schema.

    For more details, see Components | Component Summaries.

  4. XML Source

    The full XML source of the schema.

    For more details, see XML Source | Reproducing full XML schema source.

An example of Schema Overview (click on the screenshot to see a real HTML):

Generated By Template:

Schema Overview blocks are generated by schema-overview.tpl template.

Controlled By Parameters:

See Also:

DocFlex/XML | XSDDoc | Documentation Organization | Main Blocks | Schema Overview.

Schema Summaries

Schema summary is a section that provides a brief information about a certain group of XML schema files.

A schema summary may appear in the Overview Summary block (where it enumerates all documented XML schemas) and in the Namespace Summary blocks (where it shows all XML schemas that target the particular namespace).

Each schema summary is organazied as a table, in which every row displays some information about a particular XML schema file. That information may consist of two subsections:

  • Schema annotation
  • Schema profile

Schema Profile

...

Sorting of XML Schemas

...

Processing/documenting of redefinitions

...

2.  Namespaces

Namespace Overview

Generation of a separate Namespace Overview block for each namespace which includes the summaries of all XML schemas targeting that namespace and all components that belong it. Click on the screenshot to see how it looks:
For more details, see DocFlex/XML | XSDDoc | Documentation Organization | Main Blocks | Namespace Overview.

Namespace Summary

...

Namespace Profile

...

Sorting of Namespaces

...

Showing Namespace Prefixes

The original namespace prefixes defined and used in the source XSD files can be shown as parts of names of the corresponding XML schema components mentioned in the documentation. This could make the generated documentation much easier to read and understand.

Using “Show | Namespace Prefixes” parameter, you can switch on/off adding namespace prefixes to the XML names shown in the documentation.

You may want to disable the prefixes when:

  1. The same namespace prefixes are bound to different namespace URIs in different XML schemas, which you want to document together in a single documentation. Showing such prefixes all the time may only confuse the reader.
  2. The namespace prefixes used in your XML schemas are too long. In that case, showing them everywhere in the documentation may make it difficult to read.

Namespace Binding Report

Generation of the XML Namespace Bindings block, which helps to quickly find for any namespace prefix used in the source XSD documents a namespace URI associated with it and the location of where that namespace binding is specified. Click on the screenshot to see how it looks:
For more details, see DocFlex/XML | XSDDoc | Documentation Organization | Main Blocks | XML Namespace Bindings.

3.  Components

Component Documentation

For more details, see DocFlex/XML | XSDDoc | Documentation Organization | Main Blocks | Component Documentation.

Component Summaries

...

Component Profile

...

Component Usage Report

...

Sorting of Components

...

4.  XML Source

Reproducing full XML schema source

The original XML source of the whole XML schema file is reproduced in the XML Source section of the Schema Overview documentation block. Here is how it looks in HTML documentation (click on the screenshot):
When the full XML schema source is reproduced in the documentation, it plays a central role in it and is heavily cross-linked with other documentation parts (as well as within itself):
  • All component names and references in the XML schema source are hyperlinked to the respective Component Documentation blocks or local documentation sections containing all available details about those components.
  • Conversely, in the component details, you can always find a hyperlink to the component definition within the XML schema source.
  • When no details of a component are available, any references to that component anywhere in the documentation will be hyperlinked to the component definition in the XML schema source.

Generated By Template:

The full XML schema source is reproduced by schema-overview.tpl | “XML Source” stock-section, which calls from itself nodeSource.tpl to generate the most part.

Controlled By Parameters:

Details | Schema Overview | XML Source

Highlighting XML source with colors

Highlighting with separate colors the XML markup, tags, attribute names and values, XML comments and other XML source declarations.

Hyperlinks from/into XML source

Generation of hyperlinks from the schema component names and references in the reproduced XML source to the documentation generated for those components; hyperlinks to external URLs from the values of xs:anyURI attributes. See Examples | HTML Documentation.

Fragment XML source of component definitions

Reproducing of the fragment of the XML source defining each particular schema component and inclusion it in the component documentation (along with the hyperlink to the fragment's location within the full XML schema source). For example, like on this screenshot:

Removing annotation elements from XML source

Possibility to remove the entire <xs:annotation> elements from the specific fragments of the reproduced XML source (this is controlled by “... | XML Source | Remove Annotations” template parameters group). You may want to hide <xs:annotation> elements particularly when you are using XHTML to format your descriptions. In that case, the reproduced XHTML markup may occupy so much space, that it will overwhelm anything else. (In addition, there is no much need to show it within XML source, because all the annotation will be already present as a formatted text in the “Annotation” section of the component documentation).

For example, like on this screenshot:

5.  Annotations

Using <xs:annotation> elements, you can add descriptions both to your XML schema as a whole and, separately, to any components defined in it.

Note that your description text must be enclosed in <xs:documentation> element nested in the <xs:annotation> element.

Which annotation elements are processed

As you may notice, the <xs:annotation> elements can be inserted in almost any other XML Schema elements. However, currently, XSDDoc templates process only annotations specified in the following locations:
  1. 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 such an <xs:annotation> element is processed, the annotation text will get into the Annotation section of the Schema Overview. Multiple <xs:annotation> elements will produce separate “Annotation” sub-sections.

    For example, see “XMLSchema.xsd” schema overview.

  2. In definitions of global components

    Here, the <xs:annotation> element may be a child of one of the XML Schema elements:

    Such an <xs:annotation> element will be processed into an Annotation section of the Component Documentation.
  3. 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 XML Schema elements:

    Such an <xs:annotation> processed into the “Annotation” section of the Anonymous Type Detail.
  4. In definitions of local elements or global element references

    Here, the <xs:annotation> is a child of one of the local XML Schema elements:

    This annotation will be placed in the corresponding item of the Content Element Detail of the parent component.
  5. In definitions of local attributes or global attribute references

    Here, the <xs:annotation> is a child of the locally used XML Schema element:

    This annotation will be placed in the corresponding item of the Attribute Detail of the parent component.
  6. In facet definitions

    Here, the <xs:annotation> may be a child of one of the XML Schema facet elements:

    This annotation will be placed in the Facet Documentation.

XHTML formatting

Click on the screenshots to see demo:
For details, see FAQ | How to format my comments using XHTML?

Inserting images

Please, see FAQ | How to format my comments using XHTML? | How to insert images?

Rendering line breaks

For details, see FAQ | How to enable/disable interpreting line breaks in my comments?

First sentence of annotation text

...

Custom elements within annotations

...

6.  Simple Content

Datatype Model

...

Restrictions (actual facets)

...

Default/Fixed Value

...

7.  Complex Content

Content Model

Content Model Diagram

XML Representation Summary

The XML Representation Summary section, generated for each schema component, provides a schematic text representation of all possible XML elements this component describes as well as how such elements may look in XML file. This includes:
  • The list of all possible attributes an XML element may have.
  • The type and possible values for each attribute.
  • The representation of the element content, which has two different forms for a simple and complex content.
  • The element simple content is represented in the form of a data type and possible values the element may enclose.
  • The element complex content is represented with the use of extended Kleene operators (see below).
Here is how such the XML Representation Summary may look:
The Element Content Model, which represents all possible combinations of children of an element, is shown within XML Representation Summary of certain elements (see 'Content' field on the picture above), complex types and element groups.

Element Content Models are represented using Kleene operators (the same as used in DTD) extended with two more operators to cover all situations allowed by W3C XML Schemas. The following table shows all operators used in Element Content Model representations:

Operator Description
, sequence
| choice
() grouping
? 0 or 1 times
+ 1 or more times
* 0 or more times

Extended operators

× The idea of this operator can be expressed by the formula:
a × b = ((a, b) | (b, a))

This operator is used in two situations:

  1. To represent an unordered content model (which is the one defined with <xs:all> compositor)
  2. To represent a mixed content model (i.e. when any text is allowed before, between and after elements).

    For example, a content model for marked text used in messages at some programming forum web-sites (that is, a text with allowed italic, bold and code markup) may be represented as the following:

    {text} × (i? | b? | code?)*

[n1, n2] A general cardinality operator (n1 can be 0 or any number; n2 is any number or *).

This operator is used in those rare situations when Kleene cardinality operators (?, +, *) are not enough.

For example:

A+

is the same as

A[1,*]

Attribute Detail

...

Content Element Detail

...

8.  Types

Global Types

...

Abstract Types

...

Anonymous Types

...

Type Definition Detail

...

Type Derivation Tree

The Type Derivation Tree graphically depicts how a given type has been produced from all its know supertypes, which appear in the form of a tree (with mentioning the method by which a particular type has been produced from its parent type):
In the case of a derivation by union, the full supertype tree is too complicated, so it is reduced to a formula that shows only the ancestor types used directly in the declaration of the given type:

Simple Content Derivation

...

Facets

...

9.  Global Elements

Element Documentation

...

Substitution Groups

...

Abstract Elements

...

10.  Local Elements

This XML Schema documentation generator posesses a unique capability to document all local elements defined in your XML schemas. In fact, we have never seen anything like this in any other software/tool supposed to generate XML schema documentation!

About Local Elements

Local Elements are those element components that are defined locally within:
  • complex types (either global ones or defined anonymously within other elements)
  • element groups (which are separate schema components that define whole bunches of elements arranged in specific complex models).
Local elements represent a challenge to document. That is because since the introduction of local elements in W3C XML Schema language, there is no strict relationship any longer between the element name and its type for the entire scope of the XML document.

Now, within the same XML document, you may find several different XML elements that although share the same name, actually represent more or less different things and, therefore, may have different attributes and content. It is clear that such equally named but essentially different local elements must be documented separately.

On the other hand, in many cases local elements are declared very simply:

<xs:element name="elementName" type="typeName"/>
In such a declaration, an element is totally defined by its type, which is a global one. An XML schema may contain many such simple declarations, where {elementName, typeName} pairs are repeating. Therefore, the {elementName, typeName} pair itself may be considered now as an actual "global" element that could be documented as a single entity.

Two Ways of Documenting of Local Elements

Local elements can be documented simultaneously in two ways: locally and globally.

The purpose of two types of the documentation is that some elements may be important to show in the navigation lists, whereas other elements (particularly those with predefined simple content that essentially play the role of attributes) are better to be documented locally where they are defined/used. Exposing such insignificant elements in the navigation lists and summaries (along with the global elements or those with complex content) may blow out and overwhelm such lists and make them difficult to navigate.

As an example, here are two documentations generated for the same little XML schema (from “Sales Report” sample). On the left is the documentation, in which only global elements and local elements with complex type are documented separately (globally). On the right, all elements are documented separately. Click on the screenshots to view the docs:

Local Documenting

An element component can be documented locally together with its parent component where it is defined. In that case, the elements are documented essentially the same as attributes.

That documentation appears in the Content Element Detail section of the Component Documentation generated for the element's parent component. It may contain more details about the element declaration itself, but will provide less information about how the element is used elsewhere.

What exactly is included in this section for each element is controlled by the parameter group “Details | Component Documentation | Content Element Detail”.

Global Documenting

Global documenting of a local element means generating for it the full Element Documentation block/page.

In the case of framed HTML documentation, such an element will also appear in the component lists shown in the documentation List Frame (on the left).

Moreover, unlike the section describing that element in the Content Element Detail of its parent component, the detailed Element Documentation may include a lot more information about how the element interacts with other XML schema components (e.g. List of Containing Elements, Usage/Definition Locations etc.)

Which local elements get documented globally is controlled by the parameter group “Generate Details | Elements | Local Elements”. What is included in that documentation is controlled by the parameters in “Details | Component Documentation” group.

Unifying Local Elements By Type

In many XML schemas there is a common feature. Some local element components defined across a schema share the same:
{ namespace : elementName : typeName }
In that case, their definitions typically look like the following:
<xs:element name="elementName" type="typeName"/>
So, there is basically nothing (or very little) special to say about every particular such a definition.

On the other hand, the same name/type combination for a schema element is typically associated with the same notion from the real world. When you try to understand a particular XML schema, tracking something associated with different local elements scattered across the whole schema may be difficult. Having a single documentation for those elements may quickly reveal a lot more things.

This XML schema documentation generator supports such a possibility.

When the parameter “Generate Details | Elements | Local Elements | Unify By Type” is selected, all local elements that share the same {namespace : elementName : typeName} will be documented on the same global documentation page as a single entity -- unified local element.

All actual element components unified by type across the documentation will be hyperlinked to that page and all of them will be represented by a single item in various navigation lists.

If some of the definitions of the unified local element do vary (e.g. they may have different annotations or a few other settings, like default attribute) those differences will be also documented on the same unified global documentation page.

For many XML schemas, the unification of local elements by type may greatly reduce the overall number of documented elements, thereby making the documentation a lot clearer. In some special cases, the XML schema documentation generated without it would be even difficult to understand and use. All you would see would be lots of repeating element names with a little clue what they actually mean (especially given that some of them may represent essentially the same things, whereas others quite different ones.)

Example:

As an example of how the unification local elements by type works, here are two XML schema documentations generated from the same XML schema: http://www.w3.org/2001/XMLSchema.xsd.

On the left is the documentation generated with the unifying local elements by type enabled. On the right, all local elements were documented straight, without any unification. Click on the screenshots to see the docs:

All XSDDoc parameters were the same, except one: “Generate Details | Elements | Local Elements | Unify By Type”, which was checked (left) and unchecked (right).

You may quickly see the difference when you look at the navigation list (bottom-right frame) of both documentations. Browse both docs to see more.

We believe that the first documentation is a lot clearer than the second one!

Global Naming of Local Elements

Since the name of a local element is required to be unique only within the scope of its parent, there may be several local element components in a schema that share the same name but have different types and, therefore, should be documented differently (on different global documentation pages).

But when such equally named local elements need to be presented in a single navigation/reference list or summary, it may be impossible to tell them apart (at least until clicking the links).

Fortunately, that problem can be solved by extending each repeating local element name with a little text that would make the element unique across the documentation.

Such extensions of local element names are generated according to the following rules:

  1. When the element is included in the content model of only one other element (taking also into account the unification of local elements by type; see above), the element name is extended with the full name of its possible parent element like this:
    name (in full_parent_name)
    where full_parent_name is a normal qualified name for a global element or the qualified name with the extension for a local element.

    Otherwise, the element name is extended differently (as described below).

  2. If the following conditions are met
    • The element has a type attribute
    • The unification of local elements by type is enabled. (See Unifying Local Elements By Type.)
    • The element is documented globally
    then the element name is extended with the name of the type like the following:
    name (type type_name)
    or, when the name appears within the extension of other local element's name:
    name : type_name
    Here, the type_name is the qualified name of a global type specified in the type attribute.

    The conditions above guarantee that such a whole name (i.e. the element qualified name + extension) will be unique for every separately documented element entity (that is, the hyperlinks from equal names will always lead to the same documentation).

  3. In all other cases, the local element must be the one defined within a global complex type or element group.

    Indeed, any local element can be defined only in three types of locations:
    1. Within a global complex type
    2. Within a global element group
    3. Within an anonymous complex type in another element component
    The last possibility is excluded here because in that case the given local element would be included in the content model of only one other element: the one, in which it is defined.

    So, the name extension is produced from the definition location, as follows:

    name (defined in type_name complexType)
    or
    name (defined in group_name group)
    where type_name or group_name is the qualified name of the global complex type or element group, in which the element is defined.

Examples:

xs:choice (in xs:group)
Here, the local element 'xs:choice' (whose name is being extended) may be included in only one other element 'xs:group', which is the global one.
xs:group (type xs:groupRef)
The element 'xs:group' has a global type 'xs:groupRef'. This local element component is documented globally, possibly along with other equally named local elements unified by the same type.
xs:attribute (defined in xs:attrDecls group)
The local element 'xs:attribute' may be included in several other elements (documented differently) or in none at all. However, it is defined in only one location -- in 'xs:attrDecls' group.
configuration (in plugin in plugins in reporting)
The local element 'configuration' (whose name is being extended) may be included in only one other element 'plugin', which itself is also a local one included only in 'plugins' element and so on.
configuration (in plugin : Plugin)
The local element 'configuration' may be included in only one other element 'plugin', which by itself can be one or several local element components unified by the same type 'Plugin'.

Omitting Name Extensions

When the name of a local element is unique for the entire namespace, no name extension is actually needed. Besides that, you may want to suppress all name extensions for other reasons.

In those cases, you can disable the generation of name extensions using “Show | Local Element Extension” parameter, either for all local elements altogether or for only those whose original names are unique.

11.  Attributes

Global Attributes

...

Local Attributes

...

12.  Global Groups

Element Groups

...

Attribute Groups

...

Copyright© 2003-2014 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.