Document cleanup suggestions: Node

Pls. pardon a few more questions/suggestions from a language lawyer...
These are all re your description of Node.

Re childNodes: As we've seen, it's very unclear right now whether "live"
means that the individual nodes referenced by the NodeList are live, or the
NodeList itself is live and will track the children as they are added and
removed. The wording here actually seems to imply only the former, since it
says changes TO THE CHILDREN are reflected but not changes to the Node
itself -- adding a child is arguably a change only to the Node and to the
next/previous links of the children, and hence would not require that the
NodeList's membership be updated. I admit  I would strongly prefer to read
it that way... but it sounds like that wasn't your intent. Please make sure
this gets nailed down; an example or two would help.

The discussion of previous/next sibling is defined by comparison to "a
breadth-first traversal of the tree". I think you mean breadth-ONLY
traversal of the children of this one node. A real breadth-first would mean
the first child's "prevous" and last child's "next" would point to
non-siblings -- not what you intended. Beware of needless formalisms --
sometimes they obscure rather than illuminate, and may hide errors as a
result.

It looks as if insertBefore and appendChild, when passed a
DocumentFragment, should not only transfer all its contents (nice concept)
-- but should also cause the DocumentFragment to be removed from _its_
parent. Which almost makes sense, but are you really sure you want us to
make it an orphan (implicitly child of the "null DocumentFragment" we've
discussed) as opposed to keeping it around for possible reuse? If so, you
should probably warn the reader that this will happen; if not, you need to
make it an explicit exception.

One can argue that there's an obvious "Do The Right Thing" interpretation
if insertBefore or replace/remove/appendChild is called with Attribute(s)
as arguments. On the other hand, Attributes aren't children in the usual
sense, so throwing a DOMException is also a reasonable interpretation and I
_think_ it's what you intended. You might want to explicitly cite them as
an example to illustrate where the line is drawn.

The description of equals() might want to contain, or reference, the text
in clone() that describes the interpretation of shallow rather than leaving
it implicit from context. And there's some fuzziness here about exactly
what should and shouldn't be tested -- for example, will two Nodes which
belong to Documents of different DocumentTypes but otherwise have the same
structure be equal?

Received on Wednesday, 29 July 1998 19:01:02 UTC