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"/>
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.
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"
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 are documented globally is controlled by the parameter group: "Generate Details | Elements | Local Elements". What will be included in that documentation is controlled by parameters in "Details | Component Documentation" group.
namespace : elementName : typeName
}
<xs:element name="elementName" type="typeName"/>
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 (true
), all local elements that share the same {namespace : elementName : typeName}
will be documented on the same global documentation page (or block) 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.)
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:
name (in full_parent_name)
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).
type
attributename (type type_name)
name : type_name
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).
Indeed, any local element can be defined only in three types of locations:
|
name (defined in type_name complexType)
name (defined in group_name group)
type_name
or group_name
is the qualified name
of the global complex type or element group, in which the element is defined.
xs:choice (in xs:group)
'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)
'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)
'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)
'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)
'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'
.
In those cases, you can disable the generation of name extensions using "Show | Element Name Extensions" parameter, either for all local elements altogether or for only those whose original names are unique.