Re: RfC: Last Call Working Draft of DOM4; review deadline May 19

http://www.w3.org/TR/2015/WD-dom-20150428/#goals

> By consolidating DOM Level 3 Core [DOM3CORE], Element Traversal [ELEMENTTRAVERSAL], Selectors API Level 2 [SELECTORSAPI], the "DOM Event Architecture" and
> "Basic Event Interfaces" chapters of UIEVENTS [UIEVENTS] (specific type of events do not belong in the base specification),

The parenthetical doesn't make sense.

Do you mean to say "specific type*s* of events do not belong in *a*
base specification"?

> and DOM Level 2 Traversal and Range [DOM2TR], and:

> Aligning them with the needs of JavaScript where possible.

What do you mean by "JavaScript"? Do you mean "needs of JavaScript
users", "requirements of the JavaScript language", …?

> By moving features from the HTML standard that ought to be part of the DOM platform here. [HTML]

Why is [HTML] after the period instead of after "HTML"? compare:

> By defining a replacement for the "Legacy Mutation Events" of UIEVENTS [UIEVENTS] as the old model was problematic.

http://www.w3.org/TR/2015/WD-dom-20150428/#conformance

> are to be interpreted with the meaning of the key word ("must", "should", "may", etc [sic]) used in introducing the algorithm.

etc.

keyword ? -- note that RFC space is inconsistent on this, (rfc2183,
rfc2684, rfc3514, rfc4109, …)

> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",…

http://www.w3.org/TR/2015/WD-dom-20150428/#extensibility

> If vendor-specific extensions are needed, the members should be prefixed by vendor-specific strings to prevent clashes with future versions of this specification.

This doesn't sufficiently preclude clashes with other w3c DOM related
specifications :o

http://www.w3.org/TR/2015/WD-dom-20150428/#terminology

> The term context object means the object on which the algorithm, attribute getter, attribute setter, or method being discussed was called. When the context object is unambiguous, the term can be omitted.

I don't think you mean that implementers can omit the term, i think
you mean that "the specification [itself] may not include the term".

> The first child of an object is its first child or null if it has no child [sic].

I know that you are trying to avoid inconsistent wording, but here you
should use "children" and link to
http://www.w3.org/TR/2015/WD-dom-20150428/#concept-tree-child

note that you do use children later:
> Let nodes be node's children if node is a DocumentFragment node, and a list containing solely node otherwise.

http://www.w3.org/TR/2015/WD-dom-20150428/#interface-domerror

> DOMError will be nuked in favor of using DOMException exclusively. See Creating your own errors on es-discuss for more details.

es-discuss could be a link…
(yes, I know "Creating your own errors" is a link, but perhaps I want
to know what "es-discuss" is -- I'm guessing it isn't a Spanish
language discussion forum.)

> This interface is intended for other specifications that want to introduce error handling through other means than exceptions. As with exceptions, the error names table is used.

is => was, want => wanted ?

should you have "new specifications should not use this"?

> The name attribute must return the value it was initialized to.

as a pattern:

it was initialized to => to which it was initialized

> A name DOMError means a DOMError object whose name attribute is initialized to name and whose message attribute is initialized to a helpful implementation-dependent message that explains the error.

`helpful` isn't very spec-like. Realistically "to an
implementation-dependent message that should help explain the error"

http://www.w3.org/TR/2015/WD-dom-20150428/#introduction-to-dom-events

>  // great success

insert `,` after `great` :)

> Event listeners can be removed by utilizing the removeEventListener() method, passing the same arguments.

`addEventListener` wasn't linked to this point, even though it was
used in an example, so this is a bit odd.

This could be fixed by changing:

> add event listeners to observe events:

to:

add event listeners to observe events by calling addEventListener():

> if(obj.dispatchEvent(event)) {

This is the only instance of `if(` instead of `if (`, I prefer the latter :)

> Lets look at an example on how events work in a tree:

on => of

> Each time the events's target attribute value will be the span element.

event's

http://www.w3.org/TR/2015/WD-dom-20150428/#interface-event

> An event allows for signaling that something has occurred. E.g. that an image has completed downloading.

I think you should replace the period with a comma … the second
"sentence" doesn't feel like a sentence.

pattern:
>    Returns the object event is dispatched to.

Returns the object to which event is dispatched.

>    Returns the object whose event listener's callback is invoked.

is invoked => is currently being invoked

>    When dispatched in a tree, invoking this method prevents event from reaching any other objects than the current.

other objects than => objects other than
current => current object

>     Invoking this method prevents event from reaching any event listeners registered after the current one

`registered` could mean "registration order", you probably mean "any
registered event listeners"
current one => current one finishes running (or something)

> when dispatched in a tree also prevents event from reaching any other objects.

reaching => being dispatched (or propagating?) to

>     Returns true if event's goes through its target attribute value's ancestors in reverse tree order, and false otherwise.

event's => event

>     Returns true if event was dispatched by the user agent, and false otherwise.

I find this ambiguous (I know what you're trying to say, I'm not sure
you're saying it)

>     Returns the creation time of event in the number of milliseconds that passed since 00:00:00 UTC on 1 January 1970.

in => as
Note that this wording doesn't mention ignoring leap seconds, unlike:

>  When an event is created the attribute must be initialized to the number of milliseconds that have passed since 00:00:00 UTC on 1 January 1970, ignoring leap seconds.

>     When an event is dispatched to an object that participates in a tree it will be in this phase before it reaches its target attribute value.

I find the wording `reaches its target attribute value` awkward. It
sounds like the event is converting to a target attribute value,
whereas you mean that the dispatch event process reaches the point at
which currentTarget = target

http://www.w3.org/TR/2015/WD-dom-20150428/#defining-event-interfaces

> In general, when defining a new interface that inherits from Event please always ask feedback from the WHATWG or the W3C WebApps WG community.

Links here would be useful. Also, if the WebApps WG community is going
to cease to exist, there should be a way for this document once
published to point to somewhere useful (the same could apply to
WHATWG).

This document doesn't seem to mention conformance classes, but it
feels like this specific text is trying to talk about the set of
Specification Authors/Specifications that define specifications
dependent on this Spec, the wording should be clarified to indicate
that -- the passive voice / untargetted audience here isn't helpful.

http://www.w3.org/TR/2015/WD-dom-20150428/#interface-eventtarget

> Either way, callback will be invoked when event's eventPhase attribute value is AT_TARGET.

when => if | if and when (?)

> The event listener is appended to target's list of event listeners and is not appended if it is a duplicate (the event listeners in the list are unique).

uniqueness isn't defined here, but is hinted at here:

>     Remove the event listener in target's list of event listeners with the same type, callback, and capture.

if you're using the same definition, it'd be nice to not it in the
addEventListener case

>    Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or it's [sic] preventDefault() method was not invoked, and false otherwise.

its

http://www.w3.org/TR/2015/WD-dom-20150428/#dispatching-events

> Initialize event's target attribute to target override, if it is given, *or* the object to which event is dispatched *otherwise*.

> If event's target attribute value is participating in a tree, let event path be a static ordered list of all its ancestors in tree order, *and* let event path be the empty list *otherwise*.

I'm pretty sure you're using both `and` and `or` for the same purpose.
I favor `or`

I'd also favor moving "otherwise" to after the comma, as in:
> Initialize event's target attribute to target override, if it is given, otherwise the object to which event is dispatched.

(this avoids and/or)

http://www.w3.org/TR/2015/WD-dom-20150428/#introduction-to-the-dom

> Some of the nodes in the tree can have children, while others are leaves.

can/are isn't a matched pair.

are => will be

> The most excellent Live DOM Viewer can be used to explore this matter in more detail.

`most excellent` isn't a spec worthy language

http://www.w3.org/TR/2015/WD-dom-20150428/#node-tree

> Objects implementing the Document, DocumentFragment, DocumentType, Element, Text, ProcessingInstruction, or Comment interface (simply called nodes) participate in a tree, simply named the node tree.

or … interface => and … interfaces

http://www.w3.org/TR/2015/WD-dom-20150428/#mutation-algorithms

> To insert a node into a parent before a child, optionally with a suppress observers flag, run these steps:

pattern:
optionally with a => with an optional ?

> These are hooks for other applicable specifications to process the nodes that have been inserted or removed further and ensures that when multiple nodes are inserted or removed this happens atomically.

process … removed further => further process … removed
this => the insertion/removal

> This step does intentionally not pay attention to the suppress observers flag.

does intentionally => intentionally does

> This algorithm does not make any checks with regards to the node tree constraints. Use it wisely.

Use it wisely doesn't indicate an audience, i think it should be
`authors should` (as opposed to UA implementers)

> For each ancestor ancestor of node, if ancestor has any registered observers whose options's [sic] subtree is true,

pattern:
options'

-- i guess, you're using `options` as a singular thing, but that seems
unhelpful.

also, why is this in bold? usually it's in italics.

http://www.w3.org/TR/2015/WD-dom-20150428/#interface-nonelementparentnode

> The getElementById() method is not on elements for compatibility with older versions of jQuery. If a time comes where that version of jQuery has disappeared, we might be able to support it.

is there a bug / reference tracking prevalence of this?

http://www.w3.org/TR/2015/WD-dom-20150428/#interface-htmlcollection

>  Return the first element in the collection for which at least one of the following is true:

>    it has an ID which is key.
>    it has a name attribute whose value is key;
> or null if there is no such element.

the punctuation here is odd (`:`, `.`, `;`, `.`) -- should that first
`.` be a `;` ?

http://www.w3.org/TR/2015/WD-dom-20150428/#mutation-observers

> Let notify list be a copy of unit of related similar-origin browsing contexts's [sic] list of MutationObserver objects.

pattern:
contexts'

Received on Friday, 12 June 2015 17:41:42 UTC