W3C home > Mailing lists > Public > public-webapi@w3.org > June 2007

[selectors-api] Minor comments on the spec text

From: Philip Taylor <excors@gmail.com>
Date: Mon, 25 Jun 2007 14:59:41 +0100
Message-ID: <ea09c0d10706250659x46bd28f6s93ca24e7a1f64171@mail.gmail.com>
To: public-webapi@w3.org

Some comments from reading through r1.23
(<http://dev.w3.org/cvsweb/~checkout~/2006/webapi/selectors-api/Overview.html?rev=1.23&content-type=text/html;%20charset=utf-8>):

Abstract: "[CSS21]" isn't italicised.

"(often simply referred to as selector)" - the grammar sounds wrong;
should it be "...as a selector"?

"it's easier to match" - seems more conventional to say "it is"
instead. Also, ASCII ' vs some Unicode '-like symbol are used
inconsistently throughout the document.

"var cells = new Array();" - I'd say "var cells = [];" but maybe
that's just personal preference. I'd also remove the "var rows =
null;" and put the "var" inside the loop to simplify the code, though
perhaps that's a bad idea because JS scoping is weird.

"as described in [RFC2119]." vs "is that from Selectors [Selectors]."
- should be consistent on whether the citation is part of the
sentence.

""object implementing the Foo interface "." - stray space at the end.

"return "http://example.org/test"" (and another couple of places in
that section) - also probably personal preference, but I don't like
dropping semicolons (except after '}'s).

"var <var>x</var>" - seems odd to do that for just a few of the
variables (and it's inconsistent with other variables like svgImages
that are referred to in the non-code text.)

"if("test" == prefix)" - the lack of space before the '(' seems
inconsistent with all the other code.

The interface definitions have inconsistent indentation of the method names.

"The selectAllElements() methods on the DocumentSelector interface
...." - says "in document order" twice.

Is it necessary to say that exceptions thrown inside
lookupNamespaceURI must propagate outwards to the selectElement
caller? Maybe that's obvious or is defined elsewhere.

Is it necessary to say what 'this' is, when nsresolver is a Function?

"When the lookupNamespaceURI() method is invoked with an empty string
as the argument ... it must do either of the following:" - that 'must'
is redundant with the two following 'must's, which is perhaps
irritating when you're trying to extract a unique testable assertion
for each 'must' in the document.

"User agents must handle prefixes case sensitively." - does 'handle'
actually mean anything (to someone who knows more about this stuff
than I do), given that it is already stated they must be passed
case-preservingly to the NSResolver?

"var lis = document.selectAllElements("ul.nav>li"); for (var i = 0; i
< items.length; i++) {" - s/items/lis/, and for the next example.

"[CaseMap] (Non-normative) Unicode Standard Annex #21 Case Mappings" -
name isn't italicised.

"M. Davis, editor, Unicode Consortium, March 2001." - s/,/./ in the middle.

"[CSS21]: ... T. [funny symbols]elik" looks like double-encoded UTF8.
(The [Selectors] copy of the same name is fine.)

-- 
Philip Taylor
excors@gmail.com
Received on Monday, 25 June 2007 14:01:13 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 8 January 2008 14:18:57 GMT