[selectors-api] Selectors API comments: section 2

* It's not clear what the DOM3Core reference at the end of the first 
paragraph is there for.  Is that a reference for the Document and 
Element interfaces?  This could use clarification.

* It's not clear which IDL, if any, is being used when defining the 
DocumentSelector and ElementSelector interfaces.  For example, the DOM 
Level 2 Core specification has a normative OMG IDL set of interface 
definitions, with normative text that says that OMG IDL is being used. 
I see no such normative text here, which I assume is a simple oversight.

* I don't see any indication of what the language bindings for this IDL 
should look like in languages which do not support function overloading 
based on number of arguments and do not allow functions with variable 
numbers of arguments.  If it has been decided that no one is ever going 
to implement bindings for this specification in such a language , it 
might be good to explicitly say so in the specification so that it's 
clear that the problem has been considered.  Another possible solution 
is to take the approach taken in other existing DOM specifications and 
tack "NS" onto the end of the name of a namespace-aware version of a 
method that is also available in a non-namespace-aware version.  If the 
intent is to indicate that the bindings in some languages may allow 
omitting the second argument, I think that should be done via some 
mechanism that doesn't look like normative IDL.

* The text following the interface definition is difficult to read due 
to all the modifying clauses and has some grammar issues. (For example, 
what alternative does "otherwise" refer to in the second sentence of the 
first paragraph after the IDL?  What is 'it' in that sentence, given 
that the subject of the previous sentence is plural?)  I would suggest 
rewording as follows:

   The term 'first' used in the definitions of the
   querySelector methods means 'first in document order'.
   The term 'document order' means a depth-first pre-order
   traversal of the DOM tree or subtree in question.

   The querySelector() methods on the DocumentSelector interface
   MUST, when invoked, return the first Element node within the
   document which matches the group of selectors (selectors).  If there
   is no node that matches the group of selectors, the methods MUST
   return null.

and similarly for the other definitions in this section.  In particular, 
please make sure that the "that match the group of selectors (selectors) 
in document order" text goes away; I see no way to make sense of it as 
written, other than by assuming a copy/paste error.

* The "User agents must use the nsresolver argument to resolve namespace 
prefixes to namespaces or to get the default namespace. When the 
nsresolver argument is null user agents must ignore it." text is 
confusing to me.  I think what it's trying to say is more like:

   If the nsresolver argument is non-null, the user agent
   MUST look up the default namespace for the group of
   selectors by calling lookupNamespaceURI method of the
   nsresolver object with an empty string argument.

   If the group of selectors includes namespace prefixes, and
   the user-agent MUST use the nsresolver provided to resolve
   these prefixes to namespaces.  It MUST NOT use any other
   resolution mechanism.

* It's not clear whether ECMAScript authors are allowed to pass an 
NSResolver object, or whether they have to pass a Function.  This should 
be clarified.

* I would refer to "callers" or "conforming applications" and not 
"authors".  There is no reason to expect that the caller of the API will 
be an "author" in any sense of the word.

* Similarly, I'm not convinced that the term "user-agent" is better than 
"implementation" in referring to the implementation of these methods. 
We still want the term "conforming user agent" to refer to user agents 
that include an implementation of this specification, of course.

* I would replace the text

   When using namespace prefixes within selectors or if there needs to be
   a default namespace, authors must pass an NSResolver object

with:

   If the group of selectors uses namespace prefixes, or if the default
   namespace for the group of selectors is not the null namespace, the
   caller MUST pass in a NSResolver object

I think this makes it clearer.

* It's not clear what it means for a group of selectors to be "invalid". 
  Does the term mean that the group of selectors is not tokenizable 
according to the CSS grammar?  Or that there are unrecognized simple 
selectors or combinators in the group?  Or both?  How should vendor 
extensions to CSS be handled?

* Is there any requirement that the same Selectors implementation be 
used for both the implementation of this API and for CSS if the user 
agent implements both?  If there is, that needs to be stated; if not, it 
may be worth saying so.  Not sure whether this belongs in this section, 
but it came to mind when thinking about what it means for a selector to 
be "invalid".

* It's not clear to me what algorithm is used to parse the selector 
group.  This includes both issues of whitespace in the selector group 
and the issue of character escapes.  Both should be defined, either 
explicitly or by reference to the Selectors grammar as needed.  Possibly 
both for maximal clarity, though that introduces the possibility of 
divergent definitions if the Selectors grammar changes.

* It's not clear to me what "the given NSResolver does not return a 
namespace for the namespace prefix" means.  Does that mean that it 
returns a null or empty string?  Please specify.

* It's not clear to me what the note:

      The default namespace does not need to be defined.

means.  Does this mean that if the NSResolver returns a null or empty 
string when passed an empty string a NAMESPACE_ERR exception does not 
need to be raised and instead a null default namespace should be used? 
This should be clarified.

* I'm not sure what the note about pseudo-elements is trying to say, nor 
why it appears out of the blue where it does.

* The example text "The querySelector() method also accepts a group of 
selectors and it will return the first element that matches either 
selector in the group (if any)" should perhaps be:

   The querySelector() methods also accept a group of
   selectors and they will return the first element (if any)
   that matches any of the selectors in the group.

-Boris

Received on Monday, 24 December 2007 23:31:44 UTC