[Fwd: LC comments on DCI]

comments on the LC draft of DCI (http://www.w3.org/TR/dpf ) which were 
not sent to the public mailing-list.
Agreement made by the author


-------- Original Message --------

Hi DI WG,

you have requested review from the Web APIs WG, but unfortunately the
WG only just started and only few members have already joined, making
it highly unlikely that we will be able to provide feedback as a
group. I have however passed on your request to those who have
already joined, and you may get feedback from individual
participants. This is mine, and does not represent the consensus of
any group (but I'm Cc'ing Web API nevertheless so as to avoid
duplication).

To summarise my personal opinion, I feel that the DCI specification
is conceptually sound and useful in purpose, definitely something
that I look forward to using in the field. However, I have found
substantive technical issues that require modifications to the draft,
and, unless I have misunderstood parts of the current draft, would
normally warrant return for further work. Please find the detail of
my comments below.

:: Issues ::
  - Why have the nodeValue be the string "NULL" and not simply have
the null value as is usually the case for Nodes that don't have a
value? This breaks some assumptions that implementations can make and
might increase footprint for no obvious (from reading the draft) gain.

  - The valueType attribute is open-ended in what it can contain but
you don't describe how vendors should name their types, which in turn
may lead to type name clashes. You should probably recommend that
vendors name their extensions using IRIs (this doesn't mean you have
to use IRIs yourselves, you can claim that you are the only source
allowed to use plain strings). Also, why is this NULL (or null) for
DCIComponents?

  - Same comments for propertyType and DCIMetaDataInterfaceType (for
the latter, unless it is always a media type, in which case this
should be specified).

  - While the "any" type *might* make sense for a value since it
could be a simple value (e.g. an int) just as well as an object, is
that the case for DCIMetaDataInterface? Wouldn't it always something
more structured than a simple value, say at least a string?

  - *Please* don't use null to indicate a wildcard for namespaceURI
or propertyName. This is different from the way the DOM does it, and
can cause confusion as to what describes properties in no namespace.
Use the star instead ('*') as the other specificiations do.

  - Is there really a need to have both searchProperty and
hasProperty when they are so close? Experience shows that as soon as
you add a convenience method to an API, users will clamour for a
zillion others such as searchForDogFoodProperty and
getAnArmForAHandProperty. If convenience methods are needed, they are
best introduced in a second version based on experience from what
users find difficult to do (or what is inefficient to implement), as
for instance DOM 3's textContent.

  - There is confusion regarding what exceptions are to be raised,
DOMException or DCIException. You can't reuse DOMException to add
your own exception codes because that is highly likely to clash with
future extensions to the DOM, therefore DOMExceptions must only be
raised when an existing exception as specified in the DOM is raised,
for all other uses a DCIException (which could wrap a DOMException)
has to be used. It's unclear from the draft which is which. The IDL
only ever mentions DOMException with values it doesn't have (and
using the strange "raises(DOMException::FOO_ERR)" instead of just
"raises(DOMException)" with the prose saying which codes may apply)
and doesn't define DCIException (!) while other parts talk of
DCIException. Please change the draft to define the latter and to use
it when DOMExceptions don't apply.

  - I have trouble understanding the relationship between a DCI DOM
tree and a DOM tree representing an XML document. You extend Node
directly, thereby creating new node types (which is a major issue, as
future versions of the DOM itself may themselves need to add node
types, in which case you would be clashing with them -- this is *not*
a theoretical problem, you are already clashing with DOM 3 XPath[0])
but you don't clearly define the behaviour of these nodes when other
DOM operations are applied to them. What happens if someone tries to
serialise that DOM? What are the nodeName, baseURI, attributes,
childNodes, first/lastChild, next/previousSibling, ownerDocument,
prefix, or textContent set to for DCI nodes? What happens if I try to
append a DCI node as the child of an element or attribute node in the
DOM, or vice-versa? What happens when I call cloneNode,
compareDocumentPosition, getFeature, getUserData, isEqualNode,
lookupPrefix, etc. on them? The DOM defines this for the types which
inherit from Node, but you don't, which potentially opens the door to
interoperability issues as much is left to implementations. I would
recommend either a) clarifying the relationship to the DOM (which may
constitute major work and is an error-prone process), b) removing the
inheritance from Node (this requires checking that events would still
work, but so long as you inherit from EventTarget I think you're
fine), or c) defining the DCI tree as a tree of elements (which may
never be serialised as XML), and therefore inheriting from Element
(this has the advantage that they can be dumped as XML easily, but
may have issues in that you would have to specify what happens if a
DCI element is imported into another document). I think that option
(b) is likely to be the one that will remove the largest set of
issues with minimal work, especially since you don't seem to be
making much use of the fact that you inherit from Node, apart from
reusing a few fields.


:: Editorial issues ::
  - Section 2 point 5 has "To be discussed 16th Sept f2f". I assume
you don't want that in your CR document :)

  - Section 3 is a bit wooly, using terminology like "this will build
upon the types defined by the W3C DOM working group" (is it not done
already?) or "some of the common data types in the DOM include" (is
the list exhaustive or not?). It would be best to make the list
exhaustive so that implementers immediately know what they need to
reuse from the DOM, even if the definitions for the types are left to
another specification.

  - You define DOMString as "a Unicode string encoded with UTF-16". I
would drop the "encoded with UTF-16" since while that's pretty much
what the DOM and the IDL prescribe, it is something that language
specific bindings typically override as an implementation detail
(many languages map DOMString to their native string constructs,
which are often in UTF-8 internally, even though they can always
produce UTF-16 on request).

  - This is unclear: "the DOM NodeList interface when used within the
DCI context would return a DCIProperty instead of a DOM Node". I
suppose that you mean that NodeList::item() returns a DCIProperty
instead of a Node? That's somewhat wrong as in most languages that
enforce some notion of typing it won't be possible to have that
method return a type instead of another. I think you'd be better off
saying that NodeList::item() must return Nodes that can be casted to
DCIProperties, or something along those lines. Also, wherever that's
the case it needs to be specified normatively (i.e. not in a sentence
that starts with "for example").

  - Unclear as well (in 4.1): "This is independent of the event
propagation model in the host environment." I think you mean that if
the host environment dispatches events through carrier pigeons and
therefore only supports the "flying/cooing event propagation model"
it still needs to support bubble/capture for DCI, but it could be
expressed more clearly. Also, have you considered making the capture
phase optional? Some other DOMs already do that (for instance the SVG
MicroDOM). The capture phase adds implementation overhead for no
obvious value (IMHO).

  - You consistently use the word "metadata" (which seems fine to me)
yet you called the corresponding interface "DCIMetaDataInterface",
capitalising the 'D' which suggests that it's really "DCI Meta Data
Interface". CamelCase is already somewhat hard to guess, especially
for non native speakers, so being consistent and calling it
"DCIMetadataInterface" is probably best.

  - In some places you state that some attributes need to have the
value NULL, where it's unclear whether that's the string "NULL" (as
for nodeValue) or the null value. If the former then please consider
using the latter instead, and if the latter then the normal way of
flagging it in W3C specifications is to use <code>null</code>
(lowercase).

  - 5.1.2.1 "This method is used to determine whether this property
has a given named property". I find this quite hard to parse, maybe
you should tag "in its descendants" at the end?

  - In 5.3, you seem to indicate that the version is a string that
has to be "1.0" (for this version), entailing that "1", "1.0.0", etc.
are invalid and compare differently. Experience shows that if you
don't state this in excruciating detail people *will* get it wrong
and perform numeric comparisons.

  - In B.2 you use the text/javascript media type which is deprecated
in favour of application/ecmascript. Also, there is no NULL object,
just null (though since it hasn't been declared it'll resolve to
null, but it's still bad practice). If the document intends to be
XHTML (which it looks to be from the XMLDecl and the namespace) then
it MUST include the relevant DOCTYPE (yes I know that's terrible, but
complain to the HTML WG :). The second script element seems to add a
listener to the head element, it's unclear to me that this element
ever sees that event.


::Nitpicks::
  - The ob-RFC2119 reference "In this document the key words must..."
is placed in the introduction, which I assume to be informative. It
might be best to place it in the conformance chapter.
  - You mention "cell phones", AFAIK this is an americanism to which
the more generic "mobile phone" (or device) is generally preferred.
  - You talk of "URIs". The terminology this week is "IRIs".
  - When including a diagram, it's nice to also provide an SVG version.
  - "a NodeList with length attribute value of Zero": no need to
capitalise Zero.
  - "If the return value is true, the node is included otherwise, the
node is rejected" should be "If the return value is true the node is
included, otherwise it is rejected."


::Questions::
  - Do you plan on defining a metadata interface more completely in
the future, or is that completely left up to other specifications?
  - It seems to me that using the IDL "any" type may cause
compatibility issues with some languages, do you have a rationale for
not using DOMObject there?


[0]http://www.w3.org/TR/DOM-Level-3-XPath/xpath.html#XPathNamespace

-- 
Robin Berjon
    Senior Research Scientist
    Expway, http://expway.com/






-- 
Stephane Boyera		stephane@w3.org
W3C				+33 (0) 4 92 38 78 34
BP 93				fax: +33 (0) 4 92 38 78 22
F-06902 Sophia Antipolis Cedex,		
France

Received on Friday, 15 September 2006 15:46:02 UTC