Comments on DOM Level 3 Abstract Syntax draft

(Since this list has been quiet lately...)

These are my comments on the "Abstract Schemas" portion of the June 7,
2001 ASLS working draft.  The Load and Save section is not addressed
in this message.

Section 1.1, para. 1:
    The features AS-EDIT and AS-DOC are hinted at, but a different
    view on these features would be useful as well:  there are methods
    that let you *query* the schema as well as those that let you
    modify the schema, and these should be a separate feature.  I
    think the set of features can be more usefully described as:

    AS-QUERY:  Abstract Schema objects with query interfaces.
    AS-EDIT:   Abstract Schema objects with mutators.
    AS-DOC:    Document nodes with schema query interfaces.

    Since an implementor may reasonably implement the Load/Save
    features without implementing any of the AS-* features, I will
    also suggest that the error-handling support added in this draft
    be separated into a separate feature:

    ERROR-HANDLER:  Document.setErrorHandler() & related support
                    interfaces (DOMLocator, DOMErrorHandler).

Section 1.1.2, use case ASU2:
    The last sentence notes that the external subset of a DTD
    incorporates both an internal and external subset.  This doesn't
    sound right to me; is the language confused, or is this referring
    to the ability to compose the external subset using parameter
    entity references within the external subset?  If the later, I'd
    say that the language is still badly confused.

Section 1.2, ASModel.publicId and ASModel.systemId:
    Were these intended to be readonly attributes?  It is not clear
    that these should be read/write attributes; would it make more
    sense to pass the information to DOMImplementationAS.createAS()
    and DOMImplementationAS.createExternalAS().  This would be
    similar to what is currently done with Document and DocumentType
    nodes.

Section 1.2, ASModel.insertBefore():
    "inserted in the back of" seems unclear; perhaps "appended to"
    would read better.  Also note the typo in "maintaoned".

Section 1.2, ASAttributeDeclaration.ownerElement:
    The name of this attribute is misleading; it implies either a
    "one->one" or "one->at most one" relationship, which is not
    correct if attribute declarations can be shared by multiple
    elements.  For instance:

        <!ATTLIST (a|b) attr CDATA #IMPLIED>

    Could be implemented in two different ways -- using one
    ASAttributeDeclaration with an ownerElement that points to both
    the a and b elements, or two distinct ASAttributeDeclaration nodes
    which each have only one of a or b in their ownerElement list.
    Since a list is being used, I think the former is implied.  The
    intention needs to be clarified in one way or the other.

Section 1.2, ASEntityDeclaration, editor's note:
    Will parameter entities be supported by a future specification?

Section 1.3, Document.setErrorHandler():
    The Document interface does not have a base class, but it appears
    to be an extension of the Document interface from the Core
    feature.  The presence of both Document and DocumentAS in this
    section makes this less than clear, although what "makes sense"
    seems obvious.  Note also my comments about separating the error
    handler support into a separate feature from the AS-* features,
    since an implementor can reasonably want to implement Load/Save
    without implementing the AS-* features.

    As to the method itself, there needs to be some rationale as to
    why a method was used instead of an attribute, or change it to an
    attribute.  No explanation is given regarding why retrieval of the
    error handler is not supported, but it would be very useful for
    some operations (such as adding a logging layer around another
    error handler).

Section 1.3, DocumentAS:
    This interface used to support the association of multiple AS
    objects with a document is very baroque; is there a good reason
    for doing this?  Most applications should need only one AS for the
    lifetime of a document.  Supporting this feature will complicate
    basic implementations without clear benefit.

    For applications which do require such support, an extension to
    the ASModel interface can be used which allows selection of one AS
    from a set.  All of the methods from DocumentAS could be moved to
    such an "ASMultiModel" interface without any functional sacrifice,
    and allowing implementations not interested in the multi-model
    support to be more flexible in their implementations of many of
    the facilities offered by the AS-DOC feature.

Section 1.3, DocumentAS.activateAS():
    Regardless of where this method is defined, the last sentence of
    the description is an excellent example of why
    ASAttributeDeclaration.ownerElement is poorly named.

Section 1.4, NodeAS.can*(), CharacterDataAS.can*():
    These methods are listed as being able to raise DOMException, but
    no explanation is made as to when they should.  Given that a
    return of "false" should be sufficient, allowing the exception
    doesn't seem to make sense.  If the use of exceptions is
    considered appropriate, detailed explanations of which exception
    codes are used when need to be given.

Section 1.4, NodeAS.canAppendChild():
    The return value description should reference Node.appendChild(),
    not Node.AppendChild().

Section 1.4, NodeAS.canInsertBefore():
    The return value description should reference Node.insertBefore(),
    not Node.InsertBefore().

Section 1.4, NodeAS.canRemoveChild():
    The return value description should reference Node.removeChild(),
    not Node.RemoveChild().

Section 1.4, NodeAS.canReplaceChild():
    The return value description should reference Node.replaceChild(),
    not Node.ReplaceChild().

Section 1.4, Node.isValid():
    There's an extra space before the period at the end of the
    description of the "deep" parameter.

Section 1.4, ElementAS.get*(), ElementAS.contentType():
    It seems that these five methods shuld be replacable by readonly
    attributes.  That would make the API more similar to the existing
    Element interface.  The new names could simply be
    elementDeclaration, childElementNames, parentElementNames,
    attributeNames, and contentType.  This reserves implementation
    complexity and possibly runtime costs to those implementations
    which support multiple models (which have to pay that price
    anyway).

Section 1.4, ElementAS.contentType():
    Constants need to be defined for the return values.

Section 1.4, CharacterDataAS.can*():
    The explanations of the return values are bogus and need to be
    written seriously.  See also the comments on NodeAS.can*().

Section 1.4, CharacterDataAS.isWhitespaceOnly():
    This method doesn't make any sense in the AS draft.  This should
    either be in the Core feature or omitted entirely.  This is more a
    string operation which should be specified by the language binding
    for the DOMString type.  If it must be defined in the DOM, it
    should be a readonly attribute in the Level 3 Core CharacterData
    interface.

Section 1.4, DocumentTypeAS:
    There is no isNotationDefined() method, but it appears there
    should be, if only for completeness.

Section 1.4, DocumentTypeAS.isAttributeDefinedNS():
    The description of the "localName" parameter is awkward.  Perhaps
    it should read "localName with namespace" or just "localName of
    the attribute".

Section 1.4, AttributeAS.getNotation():
    Why is an exception allowed from this method when there is no
    exception for AttributeAS.getAttributeDeclaration()?  A null
    return should be sufficient.

Section 1.5:
    The Document interface from section 1.3 should be moved to this
    section.

Section 1.5, DOMLocator:
    The get*() methods of this interface should all be made readonly
    attributes for consistency with the use of attributes in existing
    DOM recommendations.  Note also that these represent the only use
    of "ID" for "identifier"; "Id" is used elsewhere and should be
    used here as well for consistency.

Section 1.5, DOMLocator.getNode():
    "NODE" should not be spelled with all caps in the return value
    description.

Section 1.9, last para.:
    This paragraph makes a little bit of sense only once the reader
    thinks about contents of comments and CDATA marked sections.
    These specific cases (and any others I've neglected) should be
    mentioned here to avoid reader confusion.  The tree itself is
    well-formed with the DOM, it's only things like comment contents
    that can cause a user to be surprised in the end.



  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Digital Creations

Received on Wednesday, 13 June 2001 14:40:04 UTC