SDD Schema Documentation Preliminary Thoughts Howard Abrams – CA, Inc.

In v1.0 Schema is just the raw XML Documentation for schema elements in spec

Example in v1.0

Example in v1.0

Proposed for v1.1 Schema would contain and tags that give the same information that is found in the spec. Benefits: – Allows schema to more easily be understood. – Allows tools to use the documentation for code completion or tooltip help.

Example in v1.1 DeploymentDescriptor is the top level element of a deployment descriptor. The DeploymentDescriptor defines the information required to support deployment of the package contents. This includes the Topology, which declares all of the resources that may participate in deployment. It also includes one atomic content element or one or more CompositeInstallable content elements. Atomic content elements are InstallableUnit, ConfigurationUnit, or LocalizationUnit. Atomic content elements define artifacts that can be processed to deploy software resources. They are atomic because they cannot aggregate other content elements. A CompositeInstallable element is the root of a content element hierarchy that defines content that performs the one deployment operation supported by the CompositeInstallable. A CompositeInstallable can define base, selectable and localization content as well as the aggregation of other content elements.

Example in v1.1

Open Issues At least in Eclipse, documentation is only shown on the element not the type. – Our schema doesn’t define top-level elements and reference them, instead we declare elements in-line and specify types. This could me more duplication of documentation. – More investigation is needed How do we make sure the schema and spec are in sync. – Some type of automation to go from xsd to word? – Make xsd the only place documentation on elements is stored?