FlexDoc/XML - XSDDoc - Parameter Tree

Specifies whether to generate the Content Element Detail section, which documents the elements declared in the element content model of the given component.

In "Generate For" nested parameter group, you can select precisely for which components this section may be generated.

In "Include" nested parameter group, you can specify which kinds of content element definitions need to be documented:

• specified in this component only
• inherited from ancestor components
• local elements
• references to global elements
• wildcards

• Elements
• Complex Types
• Element Groups

Control which kinds of content elements should be documented, for which components, how they should be sorted, how to document a particular content element.

contentElements.tpl

The parameters in this group allow you to specify exactly for which components the "Content Element Detail" section must be generated.

Specify whether to generate the «Content Element Detail» section respectively for element, complex type and element group components.

This parameter group controls which kinds of content element declarations will be documented.

Specify which local element declarations should be documented in the Content Element Detail section.

Possible Choices:

"all"

Include all local elements.

Include only local elements with simple type.

Include only local elements with complex type.

Include only local elements with anonymous type.

You may need this setting when you rely on documenting local element mostly through the Content Model Table Representation, see the parameter group:

Details | Component | Content Model | Table Representation | Content Elements

The local elements, whose type is defined anonymously within the element declaration itself, cannot be fully documented in such tables, especially those with complex content. In the last case, the attrbutes and children defined in that complex content will be lost (not documented at all), unless the top local element is documented here in Content Element Detail section.

Do not document local element declarations.

• Generate Details | Components | Elements | Local Elements
• Details | Component | Content Elements | Recursive

Specify whether to document references to global elements.

Specify whether to document the declarations of element wildcards.

wildcard.tpl

Specify whether to document in this section the declarations of content elements inherited from other (ancestor) components.

When this parameter is selected (true), both the elements declared directly within this component itself and those inherited from other (ancestor) components will be documented together. That will result in repeating of the details of the same content element declarations across the documentation of all components that inherit those content elements.

If this parameter is unselected (false), only content elements specified directly within the declaration of this component will be documented. Any content elements inherited from other components will be documented only once along with their parent components (where they are declared). Only hyperlinks to the corresponding content element details will lead from this component documentation (e.g. from the XML Representation Summary). That setting will produce a more compact documentation.

This parameter specifies how the content elements should be sorted.

When selected (true) the elements will be sorted in alphabetic order of their qualified names (with letter case ignored).

When unselected (false) the elements will follow according to some natural order determined by how and where those elements are declared:

• In the simplest case, when all content elements are declared within the same component, that will be exactly the order of their declarations.
• When the given component (whose content elements are documented) is based on other components, some of its content elements may be inherited from the ancestor components. In that case, the result element ordering will appear from the subsequent interpretation of all involved components.

When all local elements are documented locally (either in the Content Element Detail sections or Content Model Tables of their parent components), those local elements declared inside other local elements (within their anonymous types) may get lost, particularly when this goes down to substantial depth.

Example:

Here is an XML schema that requires such functionality:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="data">
    <xs:complexType>
      <xs:all>
        <xs:element name="part1" type="xs:string"/>
        <xs:element name="part2">
          <xs:complexType>
            <xs:all>
              <xs:element name="part21" type="xs:string"/>
              <xs:element name="part22">
                <xs:complexType>
                  <xs:all>
                    <xs:element name="part221" type="xs:string"/>
                    <xs:element name="part222">
                      <xs:complexType>
                        <xs:all>
                          <xs:element name="part2221" type="xs:string"/>
                          <xs:element name="part2222" type="xs:string"/>
                        </xs:all>
                      </xs:complexType>
                    </xs:element>
                  </xs:all>
                </xs:complexType>
              </xs:element>
            </xs:all>
          </xs:complexType>
        </xs:element>
      </xs:all>
    </xs:complexType>
  </xs:element>
</xs:schema>

Specifies whether to generate the Element Profile section, which contains summary information about the element (such as its type, default or fixed value, definition location).

Nested Parameters:

Control what exactly is included in the Element Profile section.

Specify whether to document the form of the element name (i.e. if it should be namespace-qualified or not).

All globally declared elements have namespace-qualified names.

For locally declared elements, their namespace qualification is specified by the 'form' attribute of the element component. When that attribute is absent, its default value is defined by the 'elementFormDefault' attribute of the parent <xs:schema>.

Possible Choices:

"any"

Document the namespace-qualified form for all element components (both global and local ones).

Document the namespace-qualified form only for locally defined element components with the explicitly specified 'form' attribute. (No default value of that attribute will be documented.)

Do not document the namespace-qualified form of the element.

Specify whether to show the element type information.

Specify whether to show the element content type and if the element is nillable.

contentType.tpl

Specify whether to document 'abstract' attribute of the element.

Applies To:

References to global elements

Specify whether to document 'block' attribute of the element declaration.

"any"

Document block attribute in any case both for the original and default value.

Document block attribute only in the case when it is specified on this element. (No default value will be documented.)

Do not document block attribute.

• References to Global Elements
• Local Elements

Specify how to document the block attribute value.

elementBlockAttrInfo.tpl

Specify whether to show the actual value of the 'block' attribute.

Notes:

• For global elements, when 'block' attribute is not specified on the component, its value will be taken from the 'blockDefault' attribute of the parent <xs:schema>.
• Empty or blank value will be ignored (treated as no-value)

Specify whether to include the text explaining the meaning of the actual 'block' attribute value.

Specify whether to document 'final' attribute of the element declaration.

"any"

Document final attribute in any case both for the original and default value.

Document final attribute only in the case when it is specified on this element. (No default value will be documented.)

Do not document final attribute.

References to global elements

Specify how to document the final attribute value.

elementFinalAttrInfo.tpl

Specify whether to show the actual value of the 'final' attribute.

Notes:

• When 'final' attribute is not specified on the component, its value will be taken from the 'finalDefault' attribute of the parent <xs:schema>.
• Empty or blank value will be ignored (treated as no-value)

Specify whether to include the text explaining the meaning of the actual 'final' attribute value.

Specify whether to show the information about the substitution groups, in which this element is involved (i.e. affiliated, head or member of). This may include:

• The list (or number) of elements which this element may substitute for.
• The list (or number) of elements that may substitute for this element.

References to global elements

Controls what exactly is included in the substitution group info.

substitutionGroupInfo.tpl

Specify whether to show the list of the substitution group heads, which this element is member of. (In other words, these are the elements that this element may substitute for.)

When false (unselected), only the number of the substitutable elements will be printed along with the link to the "Substitutes for elements" section in the Element Documentation (which, when specified, shows the same list).

See Also Parameter:

Details | Component | Related Components | Substitutable Elements

Specify whether to show the list of the members of the substitution group, which this element is head of. (In other words, these are the elements that may substitute for this element.)

When false (unselected), only the number of the substituting elements will be printed along with the link to the "Can be substituted with elements" section in the Element Documentation (which, when specified, shows the same list).

See Also Parameter:

Details | Component | Related Components | Substituting Elements

Specify whether to show the default value of the element simple content.

By default, this parameter is switched off when this parameter is selected:

Details | Component | Content Element Details | Simple Content | Default Value

Specify whether to show the fixed value of the element simple content.

By default, this parameter is switched off when this parameter is selected:

Details | Component | Content Element Details | Simple Content | Fixed Value

Specify whether to show in which component this content element is declared.

The declaration location may be different from the current component (being documented by this Component Documentation) only when the parameter

Details | Component | Content Element Detail | Include | Inherited

Specify whether to include the element annotation (full annotation text).

Specify whether to include the full description of the element.

annotation.tpl

Specify whether to document the own content model (i.e. possible attributes and child elements) of the given content element.

The content model can be represented in three different ways simultaneously:

1. Diagram
2. XML Representation Summary
3. Table Representation

See Also Parameter Groups:

• Details | Fragments | Content Model
• Details | Component | Content Model

Specifies whether to generate the Component Diagram of the given content element.

Nested Parameters:

Specify exactly for which content elements the diagram must be generated and how it should be stored.

The generation of diagram hyperlinks can be customized in the parameter group:

Details | Fragments | Content Model | Diagram | Hyperlinks

• Details | Component | Content Model | Diagram
• DiagramKit

diagram.tpl, DiagramKit.tpl

The parameters in this group allows you to specify exactly for which elements the Component Diagram section must be generated.

Each parameter imposes a specific condition on the element and its type. The section is generated when the conditions by all parameters in this group are satisfied.

Specify the possible scope of content elements for which the Component Diagram section may be generated.

Possible Choices:

"local only"

Generate this section only for locally declared elements (i.e. not those specified by reference to a global element component).

You may choose this setting when you prefer to document some (or all) local elements only locally so that the details about them appear only in the "Content Element Detail" section of the Component Documentation generated for their parent components (where those local elements are declared or used).

Generate this section regardless of the element scope.

Specify the possible types of elements for which the Component Diagram section may be generated.

Possible Choices:

"complex type only"

The section may be generated only for elements with complex types.

Generate this section regardless of the element type.

Specify how the diagrams of local elements must be stored.

If this parameter is true, the diagram files will be stored in the subdirectory structure reproducing the local element's parent component (where it is declared).

.../schemas/schemaName_xsd/elements/

.../schemas/schemaName_xsd/elements/elementName_3.png

Specifies whether to generate the XML Representation Summary of the given content element.

This section is the same as the one controlled by the parameter:

Details | Component | Content Model | XML Representation Summary

Nested Parameters:

In the nested parameter group "Generate For", you can specify exactly for which content elements this section must be generated.

More settings for the generation of XML Representation Summary are found in the parameter group:

Details | Fragments | Content Model | XML Representation Summary

xmlRep.tpl

The parameters in this group allows you to specify exactly for which elements the XML Representation Summary section must be generated.

Each parameter imposes a specific condition on the element and its type. The section is generated when the conditions by all parameters in this group are satisfied.

Specify the possible scope of content elements for which the XML Representation Summary section may be generated.

Possible Choices:

"local only"

Generate this section only for locally declared elements (i.e. not those specified by reference to a global element component).

You may choose this setting when you prefer to document some (or all) local elements only locally so that the details about them appear only in the "Content Element Detail" section of the Component Documentation generated for their parent components (where those local elements are declared or used).

Generate this section regardless of the element scope.

Specify the possible types of elements for which the XML Representation Summary section may be generated.

Possible Choices:

"complex type"

The section may be generated only for elements with complex types.

The section may be generated only for elements with simple types.

Generate this section regardless of the element type.

Specifies whether to generate the Table Representation of the own complex content described by the given content element.

only content elements with complex type (named or anonymous)

Control what is shown in the Table Representation

More settings for the generation of Table Representation are found in the parameter group:

Details | Fragments | Content Model | Table Representation

which also provides default values for some parameters in this group.

Details |

• Fragments | Component Summary | Content Model Table
• Component | Content Model | Table Representation

tableRep.tpl

The parameters in this group allows you to specify exactly for which elements the Table Representation section must be generated.

Each parameter imposes a specific condition on the element and its type. The section is generated when the conditions by all parameters in this group are satisfied.

Specify the possible scope of content elements for which the Table Representation section may be generated.

Possible Choices:

"local only"

Generate this section only for locally declared elements (i.e. not those specified by reference to a global element component).

You may choose this setting when you prefer to document some (or all) local elements only locally so that the details about them appear only in the "Content Element Detail" section of the Component Documentation generated for their parent components (where those local elements are declared or used).

Generate this section regardless of the element scope.

Specify the possible types of elements for which the Table Representation section may be generated.

Possible Choices:

"anonymous"

The section may be generated only for elements with complex types.

Generate this section regardless of the element type.

Specify whether to generate the table representation of attributes.

Control what is included in the attribute table

More settings for the generation of attribute table are found in the parameter group:

Details | Fragments | Content Model | Table Representation | Attributes

which also provides default values for the parameters in this group.

Specify whether to represent the possible value of the attribute.

The value representation will appear in the "Type / Value" column as an extension of type information.

Provided by the parameter: Details | Fragments | Content Model | Table Representation | Attributes | Value Representation

simpleContentRep.tpl

Specify whether the value representation may include the enumeration of all possible attribute values.

Provided by the parameter: Details | Fragments | Content Model | Table Representation | Attributes | Value Representation | Show Enumeration

Specify whether the attribute table will include the "Required?" column.

Default Value:

Provided by the parameter: Details | Fragments | Content Model | Table Representation | Attributes | Required

Specify whether the attribute table will include the "Declared In" column, which shows the component where each attribute/wildcard is declared.

Default Value:

Provided by the parameter: Details | Fragments | Content Model | Table Representation | Attributes | Declared In

Specify if the attribute table will include the "Description" column and which part of attribute descriptions will be displayed in it.

"full"

Display the full description of each attribute.

Display only the first sentence of the description text.

The goal of this setting is to minimize the repeating of full descriptions of attributes across the documentation.

Either the full description text or its first sentence can be displayed here, which is decided as follows:

1. If the full description consists of a single sentence, it is all what will be displayed here in any case.
2. Otherwise, if there is the full description of the attribute elsewhere, only its first sentence will be displayed here and the link to the full description added at the end.

   The full description is searched through the following locations:

   • The Component Documentation of the attribute – only in the case of the reference to a global attribute
   • The detailed documentation of the schema component, in which the attribute is declared (e.g. named complex type or attribute group, global/local element with anonymous type). The attribute full description will be searched in the Attribute Detail section or in Table Representation of the component content model.
3. If this attribute table is a part of the detailed documentation of the schema component, in which the attribute is declared, and the full attribute description is not found elsewhere, it will be printed here.

Do not include the "Description" column.

Provided by the parameter: Details | Fragments | Content Model | Table Representation | Attributes | Description

annotation.tpl

Specify whether to generate the table representation of content element model.

Applies To:

• Elements
• Complex Types
• Element Groups

Control what is included in the content element table

More settings for the generation of attribute table are found in the parameter group:

Details | Fragments | Content Model | Table Representation | Content Elements

which also provides default values for the parameters in this group.

Specify whether to represent the possible value of the child element (in case it has simple content).

The value representation will appear in the "Type / Value" column as an extension of type information.

Provided by the parameter: Details | Fragments | Content Model | Table Representation | Content Elements | Value Representation

simpleContentRep.tpl

Specify whether the value representation may include the enumeration of all possible values of the element.

Provided by the parameter: Details | Fragments | Content Model | Table Representation | Content Elements | Value Representation | Show Enumeration

Specify whether the content element table will include the "Required?" column.

Default Value:

Provided by the parameter: Details | Fragments | Content Model | Table Representation | Content Elements | Required

Specify whether the content element table will include the "Nillable?" column.

Default Value:

Provided by the parameter: Details | Fragments | Content Model | Table Representation | Content Elements | Nillable

Specify whether the content element table will include the "Declared In" column, which shows the component where each content element/wildcard/compositor is declared.

Default Value:

Provided by the parameter: Details | Fragments | Content Model | Table Representation | Content Elements | Declared In

Specify if the content element table will include the "Description" column and which part of element descriptions will be displayed in it.

"full"

Display the full description of each element.

Display only the first sentence of the description text.

The goal of this setting is to minimize the repeating of full descriptions of elements across the documentation.

Either the full description text or its first sentence can be displayed here, which is decided as follows:

1. If the full description consists of a single sentence, it is all what will be displayed here in any case.
2. Otherwise, if there is the full description of the element elsewhere, only its first sentence will be displayed here and the link to the full description added at the end.

   The full description is searched through the following locations:

   • The Component Documentation of the element – only in the case of the reference to a global element
   • The detailed documentation of the schema component, in which the child element is declared (e.g. named complex type or model group, global/local element with anonymous type). The element full description will be searched in the Content Element Detail section or in Table Representation of the component content model.
3. If this content element table is a part of the detailed documentation of the schema component, in which the child element is declared, and the full description of that element is not found elsewhere, it will be printed here.

Do not include the "Description" column.

Controls whether to show the descriptions of compositors.

Provided by the parameter: Details | Fragments | Content Model | Table Representation | Content Elements | Description

annotation.tpl

Specify whether to generate the details of the element simple content. This may include:

1. The datatype model. It shows how the element content datatype is related to the XSD basic simple types.
2. The content restrictions (that is all actual facets).
3. The default value of the element content.
4. The fixed value of the element content.

Content elements with simple content model (i.e. whose type is either a simple type or a complex type with simple content).

Controls generation of specific items

Specify whether to generate the datatype model, which shows how the element content datatype is related to the XSD basic simple types.

simpleContentRep.tpl

Specify whether to show all actual facets that restrict a possible value allowed for the element simple content.

The list of actual facets is produced as the following.

First, the initial facets are collected by all types starting from the type assigned to the element throughout the chain of all its ancestor types (both global and anonymous) until the top ancestor passed or a derivation by list or union reached.

Further, the produced sequence of facets is filtered so as the facets collected earliest (that is defined in lower descendant types) remain and those overridden by them are removed. In particular:

1. All xs:pattern facets will remain, because a value allowed for the given simple content must match all of them.
2. The xs:enumeration facets will remain those that are defined in the same type, which is either the element type itself or the one nearest to it.
3. All other facets will override the same facets defined in the ancestor types.

Specifies whether to show the annotation of each facet.

Details | Component | Content Element Detail | Type Detail | Simple Content Derivation | Facets

facet.tpl

Specify whether to include the facet descriptions.

annotation.tpl

Specify whether to show the default value of the element content.

The default value is provided by the 'default' attribute of the XSD element that declares the element component. For example:

<xs:element name="Language" type="LanguageType" default="English"/>

Specify whether to show the fixed value of the element content.

The default value is provided by the 'fixed' attribute of the XSD element that declares the element component.

When the element is declared by reference, its fixed value can be specified either in the local reference component (which is being documented here) or in the global (referenced) element component. In that case, the fixed attribute is looked for in the both components.

Specifies whether to generate the list of Possible Containing Elements.

The list shows all elements whose content models explicitly include the given element. (Here, "explicitly" means that element wildcards are not taken into account.)

elementList.tpl

Specify whether to generate the details about the definition of the content element type.

This section may include:

1. The Type Derivation Tree summary, which graphically depicts how the type was derived from the most basic types.
2. The type annotation.
3. The type derivation details, which include all facets and annotations to them. With the nested "Simple Content Derivation" parameter, you can specify whether to document the entire datatype derivation tree produced from all known XML schema components involved.

In the nested parameter group "Generate For", you can specify exactly for which content elements this section should be generated.

Other parameters control the section content.

The parameters in this group allows you to specify exactly for which content elements the "Type Detail" section must be generated.

Each parameter imposes a specific condition on the element and its type. The "Type Detail" section is generated when the conditions by all parameters in this group are satisfied.

Specify the possible scope of content elements for which the "Type Detail" section may be generated.

Possible Choices:

"local only"

The type details may be generated only for locally defined elements (i.e. not those specified by reference to a global element component).

You may choose this setting when you prefer to document some (or all) local elements only locally so that the details about them appear only in the "Content Element Details" section of the Component Documentation generated for their parent components (where those local elements are declared or used).

Generate type details regardless of the element scope.

Specify for which element types the "Type Detail" section may be generated.

Possible Choices:

"simple type"

The type details may be generated only for simple types.

The type details may be generated for any types (both simple and complex).

Specify the possible scope of the type declaration for which the "Type Detail" section may be generated.

Possible Values:

"anonymous"

The type details may be generated only in the case of an anonymous type. (The anonymous type is the one that is defined directly within the definition of the element component.)

This is the default setting because the (non-anonymous) global types are supposed to be documented separately.

The type details should be generated for any element type (regardless of its declaration scope).

Specify whether to include the element type description.

annotation.tpl

Specify whether to generate the Type Derivation Tree summary, which graphically depicts how the element type was derived from the most basic types.

typeDerivationTree.tpl

Specify whether to generate the details about the derivation of the element's simple content datatype, including all facets and (possibly) annotations.

Possible Choices:

"local definition only"

Document the datatype derivation specified only within the definition of this element (i.e. within the XSD <xs:element> element defining this element component).

"full"

Document the entire datatype derivation tree produced by all known XML schema components involved.

"none"

Do not document the datatype derivation.

Content elements with simple content model (i.e. whose type is either a simple type or a complex type with simple content).

Specify if certain features should be included in the type derivation details (e.g. full facet details, additional annotations)

simpleContentDerivation.tpl

Specify whether to show facets specified in each derivation step.

Details | Component | Content Element Detail | Simple Content | Restrictions

facet.tpl

Specifies whether the datatype derivation details should include all descriptions (e.g. facet descriptions)

annotation.tpl

Specifies whether to reproduce the XML source of the content element declaration.

Control how the reproduced XML source will look and what it should include.

nodeSource.tpl, sourceNote.tpl

Specifies if the reproduced XML should be enclosed in a box.

Specifies whether to remove all <xs:annotation> elements from the reproduced XML source fragment.

You may want to exclude the <xs:annotation> elements from the reproduced XML source because such elements may occupy a lot of space (especially, when you use XHTML to format your annotations), so they could overwhelm anything else making it difficult to read other important things. Moreover, the actual content of the <xs:annotation> elements may be already shown (as a formatted text) in the corresponding Description sections of the documentation.

See Also Parameters:

• Details | Component | Description
• Descriptions | HTML Markup