search

MPEGGroup / DASHSchema

The XML schema and example XML files for DASH (ISO/IEC 23009-1)
Other
11 stars 16 forks source link

Use formal schema documentation element rather than inline comments #71

Closed paulhiggs closed 3 years ago

paulhiggs commented 4 years ago

XML Schema defines the element which should be used to record any textual description/definition of an element or datatype (see XML Schema Annotations). This notation ensures that the description stays with the definition in XML tools such as XMLspy.

    <!-- Leap Second Information -->
    <xs:complexType name="LeapSecondInformationType">
        <xs:sequence>
            <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:attribute name="availabilityStartLeapOffset" type="xs:integer" use="required"/>
        <xs:attribute name="nextAvailabilityStartLeapOffset" type="xs:integer"/>
        <xs:attribute name="nextLeapChangeTime" type="xs:dateTime"/>
        <xs:anyAttribute namespace="##other" processContents="lax"/>
    </xs:complexType>

should be

    <xs:complexType name="LeapSecondInformationType">
        <xs:annotation>
            <xs:documentation xml:lang="en">Leap Second Information</xs:documentation>
        </xs:annotation>
        <xs:sequence>
            <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:attribute name="availabilityStartLeapOffset" type="xs:integer" use="required">
            <xs:annotation>
                <xs:documentation xml:lang="en">description of availabilityStartLeapOffset</xs:documentation>
            </xs:annotation>
        </xs:attribute>
        <xs:attribute name="nextAvailabilityStartLeapOffset" type="xs:integer"/>
        <xs:attribute name="nextLeapChangeTime" type="xs:dateTime"/>
        <xs:anyAttribute namespace="##other" processContents="lax"/>
    </xs:complexType>

Note that annotations can also be applied to elements or attributes as I have shown for one attribute above

paulhiggs commented 3 years ago

My commit converts comments from being inline (i.e. <!-- comment -->) to use the xs:documentation xml:lang="en" elements. This closely associates the comment with the element/type being defined making it easier for source-based documentation tools and IDEs