Parameter/Group |
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:
-
The order in which the namespaces are listed in the
Overview Frame
(see also “Navigation | Overview Frame” parameter).
-
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:
-
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:
|
|
Schemas
|
gen.doc.sorting.schemas : boolean
This parameter allows you to control how XML schemas are sorted throughout the documentation.
It directly affects:
-
The order in which XML schemas are listed in the
Overview Frame
(see also “Navigation | Overview Frame” parameter).
-
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:
-
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:
|
|
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:
-
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.)
-
In the case of framed documentation,
the sorting of component navigation lists.
Precisely, this is controlled via the following parameters
(for which this parameter provides the default value):
-
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 | Local Element 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).
|
|
Local Elements
|
gen.doc.element.local : enum {"all", "complexType", "none"}
Specifies whether to generate the detailed (global)
Element Documentation
for local elements
(i.e. locally defined element components).
Possible Values:
- "all"
-
Document all local elements the same way as global ones (see:
How everything is documented | 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.
Note: 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.
|
|
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.
|
|
Global Attributes
|
gen.doc.attribute : boolean
Specifies whether to generate the detailed
Global Attribute Documentation
for each global attribute component.
|
|
Attribute Groups
|
gen.doc.attributeGroup : boolean
Specifies whether to generate the detailed
Attribute Group Documentation
for each global attribute group component.
|
|
XML Namespace Bindings
|
gen.doc.xmlnsBindings : boolean
Specifies whether to generate the
XML Namespace Bindings
report.
|
