SV: DOM interfaces in the XML DOM sources

[Continuing a thread originally started in the DOM TS mailing list]

I've been in touch with Eve Maler who collects comments on the XML/DOM DTD
and would report proposed changes to her. So please add to my list.

Currently I've looked into adding more granularity to the XML definitions in
order to automatically generate tests. We obviously do not want to do this
directly from the spec, as the spec is in xhtml format and primarily for
reading.

The XML files that are transformed into the spec could be made more
granular, though. One trivial example would be to introduce an element for
the error code generated when an exception is thrown. This is currently just
given in a <p/> element (discussed in a previous mail) but could be
extended. Consider:

<raises>
 <exception name="DOMException">
 <descr>
 <p>
  WRONG_DOCUMENT_ERR: Raised if 
  <code>newAttr</code> 
  was created from a different document than the one that created the
element. 
  </p>
  <p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p> 
 <p>
  INUSE_ATTRIBUTE_ERR: Raised if 
  <code>newAttr</code> 
  is already an attribute of another 
  <code>Element</code> 
  object. The DOM user must explicitly clone 
  <code>Attr</code> 
  nodes to re-use them in other elements. 
  </p>
  </descr>
  </exception>
</raises>

(taken from the XML source for the Element interface in DOM level 1)

could in later levels of the specification be:

<raises>
 <exception name="DOMException">
 <descr>
 <p>
  <errorCode>WRONG_DOCUMENT_ERR</errorCode>: Raised if 
  <code>newAttr</code> 
  was created from a different document than the one that created the
element. 
  </p>
  <p><errorCode>NO_MODIFICATION_ALLOWED_ERR</errorCode>: Raised if this node
is readonly.</p> 
 <p>
  INUSE_ATTRIBUTE_ERR: Raised if 
  <code>newAttr</code> 
  is already an attribute of another 
  <code>Element</code> 
  object. The DOM user must explicitly clone 
  <code>Attr</code> 
  nodes to re-use them in other elements. 
  </p>
  </descr>
  </exception>
</raises>

(I've added the element errorCode around the actual error code), which would
trivially ellow for easier test generation.

/Dimitris

-----Ursprungligt meddelande-----
Från: Philippe Le Hegaret [mailto:plh@w3.org]
Skickat: den 29 maj 2001 19:49
Till: www-dom-ts@w3.org
Ämne: DOM interfaces in the XML DOM sources



The DOM specifications are completely written in XML. Everything
else (HTML, IDL, Java) is generated using a DOM generator [1].

The XML sources of the DOM specifications can be found in the zip
files available from the Overview page of each spec.

A zip with all DOM Level 2 recommendations files is available from
the DOMTR [2].

Anyway proposal to improve the markup is welcome.

Here is for example the NodeList interface:

<interface name="NodeList" id="ID-536297177">
  <descr>
    <p>The <code>NodeList</code> interface provides the abstraction of an
      ordered collection of nodes, without defining or constraining how this
      collection is implemented. <code>NodeList</code> objects in the DOM
are
      <termref def="td-live">live</termref>.</p>
    <p>The items in the <code>NodeList</code> are accessible via an
      integral index, starting from 0.</p>
  </descr>

  <method name="item" id="ID-844377136">
    <descr>
      <p>Returns the <code>index</code>th item in the collection. If
        <code>index</code> is greater than or equal to the number of nodes
in
        the list, this returns <code>null</code>.</p>
    </descr>
    <parameters>
      <param name="index" type="unsigned long" attr="in">
        <descr>
          <p>Index into the collection.</p>
        </descr>
      </param>
    </parameters>
    <returns type="Node">
      <descr>
        <p>The node at the <code>index</code>th position in the
          <code>NodeList</code>, or <code>null</code> if that is not a valid
          index.</p>
      </descr>
    </returns>
    <raises>
      <!-- No exceptions -->
    </raises>
  </method>

  <attribute type="unsigned long" readonly="yes" name="length"
             id="ID-203510337">
    <descr>
      <p>The number of nodes in the list. The range of valid child node
indices
        is 0 to <code>length-1</code> inclusive.</p>
    </descr>
  </attribute>
</interface>

Philippe

[1] http://dev.w3.org/cvsweb/java/classes/org/w3c/tools/specgenerator/
[2] http://www.w3.org/DOM/DOMTR

Received on Tuesday, 29 May 2001 17:14:21 UTC