FlexDoc/XML - XSDDoc - Parameter Tree

About XSDDoc parameters

«Generate Details» parameter group

This parameter group controls the overall content of the generated XML schema documentation.

Parameter Name / Type / Description

For Schemas

gen.doc.for.schemas

This group of parameters allows you to select which XML schema files (and components defined in them) will be documented.

The XML schema files you initially specify on the command line (or in the generator dialog) are the primary XML files to be processed by the XSDDoc template set.

However, those initial XML schemas may call from themselves some other XML schema files (via the <xs:import>, <xs:include> and <xs:redefine> elements) and they, in turn, yet more extra schemas.

All those initial and referenced XML schema files will constitute the whole your XML schema project. Generally, all of them must be loaded and processed in order to make sense of the declarations specified in your initial XML schemas. Some of the imported extra XML schemas may be the standard (and fairly big) ones used in other your projects.

So, do you need to document all the involved XML schemas? If not, which ones? That can be specified with the parameters in this group.

Initial

gen.doc.for.schemas.initial : boolean

Specify whether to document the XML schema files initially specified on the generator command line (or in the generator dialog).

You may need to unselect this parameter, when you specify a precise list XML schema files to be documented (see “Include” parameter in this group).

Imported

gen.doc.for.schemas.imported : boolean

Specify whether to document all additional XML schema files loaded by <xs:import> elements.

Note: When an XML schema is both specified initially on the command line and referred from an <xs:import> element, it is loaded only once as the initial XML schema, however, it will be marked as the imported schema as well.

Included

gen.doc.for.schemas.included : boolean

Specify whether to document all additional XML schema files loaded by <xs:include> elements.

Redefined

gen.doc.for.schemas.redefined : boolean

Specify whether to document all additional XML schema files loaded by <xs:redefine> elements.

Include

gen.doc.for.schemas.include : list of strings

With this parameter, you can add a precise list of XML schemas to be documented.

Each XML schema is specified in the list with its file name (the last name in the pathname's name sequence, e.g. "xml.xsd"). Multiple file names should be separated with the allowed item separator (';' or newline).

This parameter works in addition to other schema selection parameters (above) and won't override them.

Exclude

gen.doc.for.schemas.exclude : list of strings

Using this parameter, you can filter out some schemas from those initially selected with the parameters above.

Each excluded XML schema should be specified with its file name (the last name in the pathname's name sequence, e.g. "xml.xsd"). Multiple file names are separated with the allowed item separator (';' or newline).

Note: This parameter overrides the “Include” parameter (above). That is, when a schema file is specified in both “Include” and “Exclude” parameters, it will be excluded from the documentation scope.

Sorting

gen.doc.sorting

This parameter group allows you to control the sorting of namespaces, schemas and components throughout the whole documentation.

Namespaces

gen.doc.sorting.namespaces : boolean

This parameter allows you to control how namespaces are sorted throughout the whole documentation.

It directly affects:

  1. The order in which the namespaces are listed in the «Overview Frame» (see also “Navigation | Overview Frame” parameter).
  2. In the case of framed documentation, the order in which namespace become fully processed and documented.

    That determines which namespace gets documented the first, which, in turn, may affect the initial content of the frames:

  3. In the case of single file documentation, the order in which the full details of namespaces follow in the file.

    Those details may include the «Namespace Overview» and the details of all components belonging to the namespace («Component Documentation» blocks).

Additionally, this parameter provides the default value for another parameter: which controls the sorting of the namespace summary table.

The parameter has the following meaning:

  • When it is selected (true), the namespaces will be sorted alphabetically by their URIs (ignoring letter case).
  • When the parameter is unselected (false), the namespaces will not be sorted anyhow. In that case, the ordering of namespaces will be defined by how the initial XML schemas (to be documented) have been specified as well as how these schemas import other XML schemas.

    For more information about this, see also “Generate Details | For schemas” parameter group.

Schemas

gen.doc.sorting.schemas : boolean

This parameter allows you to control how XML schemas are sorted throughout the documentation.

It directly affects:

  1. The order in which XML schemas are listed in the «Overview Frame» (see also “Navigation | Overview Frame” parameter).
  2. In the case of framed documentation, the order in which XML schemas become fully documented (which includes the generation of the «Schema Components» and «Schema Overview» pages for a schema).

    That determines which XML schema gets documented the first, which, in turn, may affect the initial content of the frames:

  3. In the case of single file documentation, the order in which the «Schema Overview» blocks (generated for each XML schema) follow in the file.
Additionally, this parameter provides the default values of other parameters: which control the sorting of XML schema summaries.

The parameter has the following meaning:

  • When it is selected (true), the XML schemas will be sorted alphabetically by their file names (ignoring letter case).
  • When the parameter is unselected (false), the XML schemas will follow in a certain "physical" order, which is determined by how the initial XML schemas (to be documented) have been specified as well as how these schemas import other XML schemas.

    For more information about this, see also “Generate Details | For schemas” parameter group.

Components

gen.doc.sorting.comps : boolean

With this parameter you can specify at once the sorting order of components for a number of locations throughout the documentation. This includes:

  1. The sorting of components summaries.

    In fact, that is controlled via other parameters:

    However, this parameter provides the default value to all of them. (Thereby, in most cases you don't need to specify any of those parameters directly.)
  2. In the case of framed documentation, the sorting of navigation lists.

    Precisely, this is controlled via the following parameters (for which this parameter provides the default value):

  3. In the case of single file documentation, this parameter directly controls the ordering of component details (see «Component Documentation»).
The parameter has the following meaning:
  • When the parameter is selected (true), the components will be sorted alphabetically by their names (ignoring letter case).

    The component name is assumed to be one under which the component appears (is referenced to) at the given documentation location. This is typically the component qualified name (which is the actual namespace prefix plus the component local name). That, however, may be changed using “Show | Namespace Prefixes” parameter.

    Additionally, in the case of a local element, the component name may also include a special extension used to distinguish the equally named local elements. For more details about this, please see “Show | Element Name Extensions” parameter.

  • When the parameter is unselected (false), the components will not be sorted. In that case they will follow in a certain "physical" order produced according to the following.

    When the components come from different XML schemas, first, they will be grouped by their schemas. The ordering of those groups is determined by how the initial XML schemas (to be documented) have been specified as well as how these schemas import other XML schemas (see also “Generate Details | For schemas” parameter group for that matter).

    Within a group belonging to the same XML schema, the components will follow in the same order as they are defined in that schema.

    This gives you a possibility to specify a particular ordering of the components (e.g. elements) by yourself. Simply define the most important components (e.g. an XML document's root element) on the top of the XML schema. If you have several schemas to document, specify the most important of them the first. That will produce the component ordering as you wish (or something close to it).

Overview Summary

gen.doc.overview : boolean

Specifies whether to generate the «Overview Summary» documentation block.

All Component Summary

gen.doc.allcomps : boolean

Specifies whether to generate the «All Component Summary» documentation block.

Namespace Overviews

gen.doc.namespace : boolean

Specifies whether to generate «Namespace Overview» documentation blocks.

Schema Overviews

gen.doc.schema : boolean

Specifies whether to generate «Schema Overview» documentation blocks.

Elements

gen.doc.element : boolean

Specifies whether to generate the detailed «Element Documentation» for each global element component and some of the local element components (that are defined in all XML schemas being documented).

Separate Top-Level Elements

gen.doc.element.topLevel : boolean

Specify whether top-level elements should be grouped separately from all other elements (i.e. at the top of the whole element list/summary and under a separate heading).

This parameter affects:

  • All navigation list frames
  • All element summaries
  • The ordering of element details in single-file documentation (generated by SingleDoc.tpl main template)

Sorting

gen.doc.element.topLevel.sorting : boolean

Specify whether to sort the list (summary etc.) of top-level elements.

Typically, there is only one such an element. So, no sorting is needed. But in some cases, there may be several elements satisfying the top-level criteria. In that case, you may want to have them sorted.

When sorting is disabled, the elements will follow in the same order as they are defined in the schemas and those schemas are processed.

Default Value:

Copied dynamically from the value of the parameter: Generate Details | Sorting | Components

Local Elements

gen.doc.element.local : enum {"all", "complexType", "none"}

Specifies whether to generate the detailed (global) «Element Documentation» for local element (i.e. locally defined element components).

Possible Values:

"all"
Document all local elements the same way as global ones (see: Documenting of local elements | Global Documenting).
"complexType" (or "with complex type only" as value name)
Generate the detailed «Element Documentation» only for local elements with complex types.

Certain XML schema design patterns avoid using global element components almost entirely. Instead, they define a single global element component that describes the root element of a possible XML document. Any other elements, which may be contained in that XML document, are defined using only global types and local element components. What is more, frequently, those XML schemas also avoid defining element attributes. Instead, to store in an XML document the elementary data normally supposed for attributes, they define lots of local elements with primitive simple types. As a result, such an XML schema contains great a lot of insignificant local element components. When all of them are documented separately (and appear in main element component lists) they may overwhelm anything else. This parameter value allows you to avoid exactly such a mess and properly document your XML schemas written according to that pattern!

"none"
Do not generate separate «Element Documentation» for local elements.

Unify By Type

gen.doc.element.local.unifyByType : boolean

Specify whether to unify local elements by type.

If true, all local elements that share the same name (in the same namespace) and the same global type are documented as a single entity – unified local element.

If false, every local element component will be documented separately.

For more details, please see Unifying local elements by type.

Store By Parents

gen.doc.element.local.storeByParents : boolean

Specify how the documentation of local elements (and their diagrams) must be stored.

When this parameter is true, all documentation files for local elements will be stored in the subdirectory structure reproducing their parent components (in which they are defined).

Namely, for a local element 'localElementName' defined in a parent component, its documentation file will be stored as follows:

Parent Component Element Documentation File
global complex type
'typeName'
.../schemas/schemaName_xsd/complexTypes/typeName/localElementName.html
global element group
'groupName'
.../schemas/schemaName_xsd/groups/groupName/localElementName.html
global element
'elementName'
.../schemas/schemaName_xsd/elements/elementName/localElementName.html
another local element
'elementName'
.../schemas/schemaName_xsd/.../elementName/localElementName.html

At that, the subdirectory structure of the parent element will be reproduced at any depth according to the rules above.

That system will allow you to know precisely where each element documentation (or diagram) file is located (according to where the element is defined in the schema). So, you will be able to reference it from outside.

The component diagrams are stored in the same directory along with the component documentation files under the same names however with different extension (corresponding the image format), e.g.:

.../schemas/schemaName_xsd/complexTypes/typeName/localElementName.html
.../schemas/schemaName_xsd/complexTypes/typeName/localElementName.png

When this parameter is false, all element documentation files are stored in the same directory:

.../schemas/schemaName_xsd/elements/
When the element name is repeating (which is possible for local elements), the file name will be extended with a numeric suffix, e.g.:
.../schemas/schemaName_xsd/elements/elementName_3.html
Which particular number is used in the suffix is unpredictable. (Its only purpose is to make the file name unique.) That will make impossible to reference the documentation/diagrams of such elements from outside!

However, if you don't need this, the produced HTML documentation files will be more compact (as all links to local element docs will be shorter).

Note:

This parameter can be used only when the unification of local elements by type is disabled (see “Generate Details | Elements | Local Elements | Unify By Type” parameter).

When the unification by type is enabled, several local elements defined in different locations may get documented in the same documentation file. This breaks the whole idea of storing element docs according their definition locations! In that case, this parameter is disabled and false.

Complex Types

gen.doc.complexType : boolean

Specifies whether to generate the detailed «Complex Type Documentation» for each global complex type component.

Simple Types

gen.doc.simpleType : boolean

Specifies whether to generate the detailed «Simple Type Documentation» for each global simple type component

Element Groups

gen.doc.group : boolean

Specifies whether to generate the detailed «Element Group Documentation» for each global element group component.

Attribute Groups

gen.doc.attributeGroup : boolean

Specifies whether to generate the detailed «Attribute Group Documentation» for each global attribute group component.

Global Attributes

gen.doc.attribute : boolean

Specifies whether to generate the detailed «Global Attribute Documentation» for each global attribute component.

XML Namespace Bindings

gen.doc.xmlnsBindings : boolean

Specifies whether to generate the «XML Namespace Bindings» report.