Re: [selectors-api] Selectors API comments: section 2

Boris Zbarsky wrote:
> * 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.

Yes, that was the intention. I have attempted to clarify it.

> * 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.

This issue has not yet been addressed.

> * 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.

This issue has not yet been addressed.  These two issues above will 
likely be addressed by using and referencing Language Bindings for DOM 
Specifications.

> * 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.

I have modified the text to clarify those, and other issues, based on 
your suggestion.

> * 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.

The process used to resolve namespaces was already defined elsewhere in 
the spec.  However, I clarified that paragraph to more clearly refer to 
those definitions.

> * 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.

This has been clarified by defining that ECMAScript implementations must 
support both a function and an object, and that authors may use a 
function instead.

> * 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.

I now refer to conforming applications.

> * 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 have replaced the relevant uses of "user agent" throughout the spec 
with "implementation".

> * 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 have updated the text based on your suggestion.

> * 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?

The Selectors specification defines the conformance criteria for a group 
of selectors, and thus an invalid selector is one that does not conform 
to those requirements.  I have updated the text to more clearly refer to 
the conformance requirements in Selectors.

> * 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".

I do not believe specific implementation details such as that belong in 
the specification.  As long as the resulting implementation conforms to 
the spec, it is irrelevant whether the user agent shares the selectors 
implementation between this and CSS, or redundantly implements it twice 
(despite the fact that doing so would not be wise for the implementor).

> * 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.

The spec now defines that the selectors must be processed according to 
the grammar specified in the Selectors specification.

> * 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.

I have made this clarified this to say an empty string, or equivalent.

> * It's not clear to me what the note:
> 
>      The default namespace does not need to be defined.
> 
> means.

I have clarified the note to say that unresolvable namespaces can only 
occur for prefixes, since the resolving the default namespace will 
always resolve to something.

> 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.

How to interpret such return values is defined in the algorithm to get 
the default namespace.

> * 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.

This has been moved up to the section where the spec defines how to 
process selectors, and has been rephrased as an advisory to authors 
about the use of pseudo-elements.

> * 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.

Your suggested text has been added to the spec.

The remaining issues in this mail that have not yet been addressed will 
be addressed in the near future.

Please see the latest version of the spec in CVS to review the changes.
http://dev.w3.org/2006/webapi/selectors-api/

Please let me know if you are not satisified with any of these responses 
or changes.

-- 
Lachlan Hunt - Opera Software
http://lachy.id.au/
http://www.opera.com/

Received on Thursday, 14 February 2008 13:34:46 UTC