Re: Call for Consensus - Selectors API to Candidate Rec

On Thu, Feb 5, 2009 at 2:21 AM, Charles McCathieNevile <chaals@opera.com> wrote:
> [1] http://dev.w3.org/2006/webapi/selectors-api/

I've been meaning to read this for months. sorry for the delay, i
expect none of my comments are significant, but i enjoy reading and
writing....

> This specification introduces two methods that take a group of selectors
>  it requires a script like the following that iterates

that => which ?

> With these methods, it is easier to match a set of Element nodes based on specific criteria.

easier than what? (yes, i know the next sentence would explain, but I
don't think English allows for that.)

> The implementation must first trim any leading or trailing whitespace from the value of the selectors parameter.

or => and ?

> If the user agent also supports some level of CSS, the implementation should support the same set of selectors in both these APIs and CSS.

This is poorly written, at first parse I concluded that selectors
weren't CSS (there is no CSS level 0), and CSS3 comes in modules.

The goal is presumably to indicate that if some other entrypoint to
CSS supports something, then this API should support the same thing
with the same syntax. But it didn't manage to read that way.

> The NodeList object returned by the querySelectorAll() method must be static, not live.
> ([DOM-LEVEL-3-CORE], section 1.1.1) Subsequent changes to the structure of the underlying document must not be reflected in the NodeList object.

I believe that the parenthetical should be part of the first sentence
instead of after the period.

> DOM3 Core defines several methods for checking for interface support, or for obtaining implementations of interfaces, using feature strings.
> ([DOM-LEVEL-3-CORE], section 1.3.6) A DOM application can use these methods, each of which accept feature and version parameters, using the values "Selectors-API" and "1.0" (respectively).

I believe that the parenthetical should be part of the first sentence
instead of after the period.

note that you do sometimes put the period after, as in:
> If the group of selectors include namespace prefixes that need to be resolved, the implementation must raise a NAMESPACE_ERR exception ([DOM-LEVEL-3-CORE], section 1.4).

> var x = document.querySelector("#foo, #bar");
> x would contain the first element in the document with an ID of either foo or bar (or both).

1. could you change 'contain' - i read contain to mean list, which of
course is wrong for querySelector()

anne suggests "be"

2. it might be null - or whatever the return is for the case where
there's no match
3. i think the '(or both)' bit doesn't add value, even understanding
the case where there's a node matching #foo#bar, if it's the first
that matches #foo or #bar, it's still the first that matches #foo or
#bar and the fact that it matches #foo#bar is absolutely irrelevant

> The methods can also be invoked on elements.

The methods _defined in this specification_ ...

> In ECMAScript, the language binding also allows NodeLists to be addressed using the array notation, so that loop could be rewritten like this:

using array notation

> This would cause each selected element to be removed from the DOM, but each element will remain in the NodeList.
> If the list were a live NodeList, removing an item from the DOM would also remove the element from the list and adjust
> the indexes of subsequent elements. That would have adverse effects upon the loop because not all selected elements
> would be processed.

I know that explanatory text is valuable, but i don't particularly
like this explanatory text in a normative section. Could you make this
a non-normative note?

> excluding all others, requires an additional processing to filter the result.

requires additional processing, or an additional step

Received on Monday, 9 February 2009 10:17:12 UTC