Site Map   PRODUCTS ----------------------------------- DocFlex Technology    About    Key Features    Data Processing    Formatting    Templates / Designer GUI    Documentaion   DocFlex/XML    About    Documentaion        Installation & Config Files        Running Generator         Designing Templates    Sample        XMLDoc        Sales Report        Alternative to XSLT    XSDDoc        Features        Organization        Examples        Templates            Subtemplates            Parameters        FAQ    Integrations        Apache Ant        Apache Maven        XMLSpy    Tutorials   DocFlex/Javadoc    About    Documentaion    Templates    Examples    Tutorials   DocFlex/Together    About    Examples    Basic Templates    Documentaion    Tutorials   TRY ----------------------------------- Downloads Registration Trial License   BUY ----------------------------------- Licensing/Pricing Shop   COMPANY ----------------------------------- News Products Services Customers About Us Imprint Legal    Terms of Use    Business Terms & Conditions    End User License Terms Contact Links

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

1. XML Schemas
   • Support of any XML schema design patterns
   • Schema Overview
   • Schema Summaries
   • Schema Profile
   • Sorting of XML Schemas
   • Processing/documenting of redefinitions
2. Namespaces
   • Namespace Overview
   • Namespace Summary
   • Namespace Profile
   • Sorting of Namespaces
   • Showing Namespace Prefixes
   • Namespace Binding Report
3. Components
   • Component Documentation
   • Component Summaries
   • Component Profile
   • Component Usage Report
   • Sorting of Components
4. XML Source
   • Reproducing full XML schema source
   • Highlighting XML source with colors
   • Hyperlinks from/into XML source
   • Fragment XML source of component definitions
   • Removing annotation elements from XML source
5. Annotations
   • Which annotation elements are processed
   • XHTML formatting
   • Inserting images
   • Rendering line breaks
   • 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
   • Attribute Detail
   • Content Element Detail
8. Types
   • Global Types
   • Abstract Types
   • Anonymous Types
   • Type Definition Detail
     • Type Derivation Tree
     • Simple Content Derivation
     • Facets
9. Global Elements
   • Element Documentation
   • Substitution Groups
   • Abstract Elements
10. Local Elements
    • About Local Elements
    • Local Documenting
    • Global Documenting
      • Global Interpretation of Local Elements
      • Global Naming of Local Elements
      • Global Documentation for Local Elements
11. Attributes
    • Global Attributes
    • Local Attributes
12. Global Groups
    • Element Groups
    • Attribute Groups

1.  XML Schemas

Support of any XML schema design patterns

So, how do all those “creatures” differ one from another in respect of documenting them? Or asking it otherwise, what might be common?

If you look closely into this, you could notice that all XML schema design patterns come down to a few specifics, all of which can be addressed by a single documentation approach:

• The entire XML schema is broken into a number of XSD files, some of which import/include others.

  You don't need to do anything special about this. Both <xs:import> and <xs:include> XSD elements are supported. All referenced schemas will be automatically loaded and documented.

  Moreover, using template parameters:

  • Generate Details | For Schemas | Imported
  • Generate Details | For Schemas | Included
  you can even specificaly disable documenting of imported/included schemas (even though they will be processed still).
• There are several XSD files and some of them redefine certain components declared within others.

  That is done using <xs:redefine> XSD elements, which are supported by DocFlex/XML XSDDoc very well!

  See: XML Schemas | Processing/documenting of redefinitions

• Some elements are declared locally. Such elements may have equal names yet different content models. Locally declared elements are used instead of attributes to hold simple data.

  In fact, that was exactly one of the main goals of this XML schema documentation generator to document properly the local element declarations!

  Some locally declared elements may share the same name, yet have different content models. Others may be absolutely identical to each other (that is have equal names and based on the same global type), yet they are declared separately in numerous locations. On top of that, there may be lots of insignificant locally declared elements with simple content that effectively serve the role of attributes of their parent complex elements.

  If you document all of this straight (which is actually what all other known XML schema doc-generators currently do!), in certain cases you may get in your XML schema documentation a mess made of numerous repeating local element names, in which it could be hard to find some useful information.

  DocFlex/XML XSDDoc provides three ways to deal with that problem:

  1. Extension of local element name

     When several locally declared elements have the same name but different content models, to distinguish them one from another across the documentation, the element names can be extended so us to make them unique. This is controlled by “Show | Local Element Extension” parameter.

     For more details, see Global Naming of Local Elements.

  2. Quasi-global elements

     All those locally declared elements that share the same name and are based on the same global type (which means they have the same content model) are represented and documented as a single entity called “quasi-global element”. That may substantially reduce and clarify the documentation!

     For more details, see Global Interpretation of Local Elements.

  3. Local vs. global documenting of local elements

     When some elements are declared locally within another (parent) element and used only to hold some simple data items associated with the parent (that is, they serve as parent element's attributes), such elements can be documented only locally within the details of the parent element.

     That functionality is controlled by “Generate Details | Elements | Local Elements” parameter. It may help to reduce the documentation as well as to clear up and clarify various element navigation lists and summaries!

     For more information, see Local Elements | Local Documenting.

• There are groups of globally declared elements that are referenced in the XML schema via single (abstract) elements representing any element in a group.

  Such element groups, called substitution groups, are specifically recognized and documented by DocFlex/XML XSDDoc.

  See: Global Elements | Substitution Groups

• The order in which elements/attributes are declared is important.

  Using the following template parameters you can preserve the original ordering of your elements/attributes at various locations of the documentation:

  • Generate Details | Sorting | Components
  • Details | Component Documentation | XML Representation Summary | Sorting
  • Details | Component Documentation | Attribute Detail | Sorting
  • Details | Component Documentation | Content Element Detail | Sorting
• The XML schema declares a possible root XML element that needs to be highlighted in the documentation.

  In general, the W3C XML schema specification itself provides no functionality to assign which of the XML elements declared in an XML schema must be the root of any XML document that complies with that schema.

  However, you can solve this problem by placing the declaration of the root element the first in the XML schema.

  Further, when you generate documentation for that XML schema, unselect the “Generate Details | Sorting | Components” parameter so that the original order of element declarations will be preserved in the documentation.

  If your XML schema is broken into several XSD files, specify the one of them that contains the root element declaration to be processed the first by the generator (see also FAQ | How to generate a single documentation by multiple XML schemas?) and unselect the “Generate Details | Sorting | Schemas” parameter.

  That will ensure that the root element gets on the top of various navigation lists and summaries, which will highlight its special role.

Schema Overview

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:

• “Generate Details | Schema Overviews” parameter specifies whether to generate the Schema Overview block.
• “Details | Schema Overview” parameter group controls what is included in the Schema Overview block.

See Also:

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

Schema Summaries

Schema Profile

Sorting of XML Schemas

Processing/documenting of redefinitions

2.  Namespaces

Namespace Overview

Namespace Summary

Namespace Profile

Sorting of Namespaces

Showing Namespace Prefixes

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

3.  Components

Component Documentation

Component Summaries

Component Profile

Component Usage Report

Sorting of Components

4.  XML Source

Reproducing full XML schema source

• 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

Hyperlinks from/into XML source

Fragment XML source of component definitions

Removing annotation elements from XML source

For example, like on this screenshot:

5.  Annotations

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

Which annotation elements are processed

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:

   <xs:element> <xs:complexType> <xs:simpleType>

   <xs:group> <xs:attribute> <xs:attributeGroup>

   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:

   • <xs:complexType> (type xs:localComplexType)
   • <xs:simpleType>  (type xs:localSimpleType)
   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:

   • <xs:element> (type xs:localElement)
   • <xs:element> (type xs:narrowMaxMin)
   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:

   • <xs:attribute>
   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:

   <xs:enumeration> <xs:fractionDigits> <xs:length> <xs:maxExclusive> <xs:maxInclusive> <xs:maxLength>

   <xs:minExclusive> <xs:minInclusive> <xs:minLength> <xs:pattern> <xs:totalDigits> <xs:whiteSpace>

   This annotation will be placed in the Facet Documentation.

XHTML formatting

Inserting images

Rendering line breaks

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 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).

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: To represent an unordered content model (which is the one defined with <xs:all> compositor) 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

Simple Content Derivation

Facets

9.  Global Elements

Element Documentation

Substitution Groups

Abstract Elements

10.  Local Elements

About Local Elements

• 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).

On the other hand, that approach should not be extended to all local elements, because in lots of cases local elements are declared very simply:

<xs:element name="elementName" type="typeName"/>

This XML Schema documentation generator is able to document local elements simultaneously in two ways: locally and globally.

Local Documenting

In that case, the element will be treated essentially the same as an attribute. (Actually, locally defined elements with simple types are frequently used as a replacement of attributes.)

The details about such an element will appear in the "Content Element Detail" section of the Component Documentation generated for its parent component.

Global Documenting

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 a section describing that element in the "Content Element Detail" of its parent component, the detailed Element Documentation may contain substantially more information (such as "List of Containing Elements", "Usage/Definition Locations" report and etc.)

Global Interpretation of Local Elements

For instance, those elements that duplicate the same definition across the whole XML schema (e.g. the name and type) may be considered to represent the same kind of things from the outside world. Therefore, all such elements may be represented by the same global element entity and documentation as a single unit.

We solve this problem in the following way:

1. When several local elements share the same name and their type is determined by the 'type' attribute referring to the same global simple or complex type, all such local elements are considered as a single quasi-global element.

   Unlike ordinary global elements whose names are unique for the whole namespace, each quasi-global element is unique only by its name/type combination. Most of things that can be said about every local element with the equal name/type combination are the same and, therefore, may be referred to and documented as a single unit.

   Actually, such an approach may be even more interesting, because the same name/type combination for a schema element is normally associated with the same thing 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 this may quickly reveal a lot more details.

   Each quasi-global element is documented separately and is referred to from every location of the corresponding local elements it represents. Conversely, the unified documentation for a quasi-global element will account and mention all locations where all actual local elements represented by it are declared.

2. Local elements with embedded anonymous types may be considered as truly local ones. The presence of the embedded type means that such an element is associated with something relevant to only that particular local context where it is defined. Because of this, each local element with anonymous type is documented with a separate Element Documentation block/page.

   There are some XML schemas which contain a number of local element components with the same names and absolutely equally defined anonymous types embedded in them. All such local elements again represent the same unique global entity and it will not be accounted in the documentation. Fortunately, that kind of design is very rare.

Global Naming of Local Elements

The extension of local element name is generated according to the following rules:

1. When the element is included in the content model of only one other globally documented element (that is taking into account quasi-global elements; see above), the element name is extended with the full name of its possible parent element like the following:

   name (in full_parent_name)

2. Otherwise, when this is a quasi-global element (see above), the element name is extended with the type name like the following:

   name (type type_name)

   or

   name : type_name

   when the name appears within the extension of other local element's name.
3. The rest is the case when the element has anonymous type and is declared locally within a global complex type or element group. In that case, the element name is extended with a short info how its anonymous type was derived from other global types:

   name (type extension of global_type_name)
name (type restriction of global_type_name)
name (type list of global_type_name)
name (type anonymous)

   (The last is the case when the anonymous type was not derived directly from a global type by extension, restriction or list.)

   Theoretically, such name extensions may still be repeating for different local elements. However, in practice that will happen very rarely.

Examples:

xs:choice (in xs:group)

Here, the local element 'xs:choice' (whose name is extended) may be included in only one other element 'xs:group' which is the global one.

configuration (in plugin in plugins in reporting)

The local element 'configuration' (whose name is extended) may be included in only one other element 'plugin', which is by itself a local element included only in element plugins and so on.

configuration (in plugin : Plugin)

The local element 'configuration' may be included in only one other element 'plugin', which is also a local element. However, what's know more about that element is that its type is 'Plugin' and it appears in content model of several other elements.

Omitting Local Element Name Extensions

Global Documentation for Local Elements

11.  Attributes

Global Attributes

Local Attributes

12.  Global Groups

Element Groups

Attribute Groups