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

On Fri, Jun 12, 2015 at 7:41 PM, timeless <timeless@gmail.com> wrote:
> http://www.w3.org/TR/2015/WD-dom-20150428/#goals

I recommend only reviewing

  https://dom.spec.whatwg.org/

going forward. It's more up to date and would have saved you some
time. You can review my changes in response to your comments here:

  https://github.com/whatwg/dom/commit/abd00ec7dcdd66b337db20f60710058655304648


> The parenthetical doesn't make sense.

Fixed.

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

Added "ecosystem".


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

Because there's no good convention for references. I sort of feel we
should maybe start inlining them and maybe have a summary at the end,
but not sure.

> etc.

Fixed.

> keyword ?

Sure. Changed except in the title of the RFC. Might add [sic] at some
point I suppose.

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

Rewrote this section to make more sense given today's POV on vendor prefixes.

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

Hmm. I left this as is for now. It will be obsoleted by new IDL
terminology anway:

  https://www.w3.org/Bugs/Public/show_bug.cgi?id=27301

> 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

Fixed.

>> DOMError will be nuked in favor of using DOMException exclusively.

This already happened so I skipped this part of the review.

>>  // great success
>
> insert `,` after `great` :)

You're missing out on a meme.

> This could be fixed by changing:
>
>> add event listeners to observe events:
>
> to:
>
> add event listeners to observe events by calling addEventListener():

Done.

>> if(obj.dispatchEvent(event)) {
>
> This is the only instance of `if(` instead of `if (`, I prefer the latter :)

The latter instances are not code, so I'll keep this as-is since I
prefer this style.

> on => of

Fixed.

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

Fixed.

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

Done.

> Returns the object to which event is dispatched.

Fixed.

> is invoked => is currently being invoked

Fixed.

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

Fixed.

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

Fixed.

> reaching => being dispatched (or propagating?) to

Left as-is. Reach seems fine.

> event's => event

Fixed.

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

Left as-is for now, if that construct needs to change, so do many
others and I don't really want to deal with that right now.


> in => as

Done.

> Note that this wording doesn't mention ignoring leap seconds, ...

This wording is never as precise as the actual normative text.

> 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

I don't follow this.

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

Added links. If any of that happens we'll update the document.

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

You'll have to be more specific. I recommend filing issues on GitHub
by the way. Or even better, provide pull requests with changes.

>> Either way, callback will be invoked when event's eventPhase attribute value is AT_TARGET.
>
> when => if | if and when (?)

I don't understand what's wrong here.

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

I don't really understand this either. Note that these are not the
definitions. Just non-normative text.

> its

Fixed.

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

I've settled on "and" and "otherwise" at the end a while ago. If you
want to change this I'll need pull requests for a bunch of
specifications. Not going to go through all of that again.

>> Some of the nodes in the tree can have children, while others are leaves.
>
> can/are isn't a matched pair.
>
> are => will be

Does "are always" work? Because that was more what I was going for I think.

> `most excellent` isn't a spec worthy language

For non-normative text that seems totally fine to me.

> or … interface => and … interfaces

Thanks. Hopefully IDL changes soon so we can just to call these things classes.

> pattern:
> optionally with a => with an optional ?

Done.

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

This text no longer exists.

> does intentionally => intentionally does

Was already fixed.

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

Actually, specification authors need to. Added.

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

Fixed I think.

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

Variables are in italic. Definitions and object slots are in bold typically.

> is there a bug / reference tracking prevalence of this?

Not sure.

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

Yeah, though at some point this should be rewritten I think.

> pattern:
> contexts'

Done.

I added you as timeless to the acknowledgments. If you want me to use
your real name, let me know!


-- 
https://annevankesteren.nl/

Received on Monday, 15 June 2015 07:56:45 UTC