How to exclude XSD elements from documentation [closed] - xsd

Question

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
I have an XSD that I'm editing, and, using a tool such as XMLSpy or oXygen, I'd like to generate user documentation for the XSD. However, I'd like to exclude certain elements from the documentation (based on user requirements). What would be the best approach to do this?

Answer 1

There's no tool-independent way to exclude elements from documentation.
There's xsd:annotation/xsd:appinfo for application-oriented data.
There's xsd:annotation/xsd:documentation for human-oriented data.
XSDs are XML, so writing an XSLT transformation is certainly one way to generate documentation. Note, however, that the semantics of XSD are complex enough that the exclusion of any given element will be trivial relative to the rest of the task.

Answer 2

Removing elements from documentation is a three-part process:
1. Add an attribute to the the elements to indicate whether or not they should be documented.
Following is a code sample showing an XSD with three elements, and a new attribute, generateDocumentation, that indicates whether the element should be documented.
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="documentation.xslt"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:mc="http://www.mycompany.com"
xsi:schemaLocation="http://www.mycompany.com ./doc.xsd"
elementFormDefault="qualified" attributeFormDefault="unqualified">
<xs:element name="DocumentedElement" mc:generateDocumentation="true"/>
<xs:element name="UndocumentedElement" mc:generateDocumentation="false"/>
<xs:element name="DefaultElement"/>
</xs:schema>
Specifics on how to extend XSD with custom attributes can be found here.
Note that, in this example, elements without the generateDocumentation attribute defined will be documented by default.
2. Apply a transformation to remove elements with attribute values indicating that they should not be documented.
The following XSLT will remove elements that have mc:generateDocumentation="false" or mc:generateDocumentation="0", and will strip the resulting white space:
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:mc="http://www.mycompany.com">
<xsl:output method="xml" version="1.0" encoding="UTF-8" indent="yes"/>
<!-- Identity transform -->
<xsl:template match="/ | #* | node()">
<xsl:copy>
<xsl:apply-templates select="#* | node()"/>
</xsl:copy>
</xsl:template>
<!-- Undocumented elements -->
<xsl:template match="*[#mc:generateDocumentation='false'] | *[#mc:generateDocumentation='0']"/>
<!-- Strip white space -->
<xsl:template match="*/text()[normalize-space()]">
<xsl:value-of select="normalize-space()"/>
</xsl:template>
<xsl:template match="*/text()[not(normalize-space())]"/>
</xsl:stylesheet>
This transformation produces the XSD with the specified elements removed:
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="documentation.xslt"?>
<xs:schema xmlns:mc="http://www.mycompany.com"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.mycompany.com ./doc.xsd"
elementFormDefault="qualified" attributeFormDefault="unqualified">
<xs:element name="DocumentedElement" nc:generateDocumentation="true"/>
<xs:element name="DefaultElement"/>
</xs:schema>
3. Use the tool of your choice to generate the user documentation.