Re: Review of DOM Living Standard — Last Updated 20 June 2015

Commit: https://github.com/whatwg/dom/commit/e90ae2844f71b66a0339ef6e533bf6850238f069

On Tue, Jun 23, 2015 at 12:41 AM, timeless <timeless@gmail.com> wrote:
> this is missing from the green box:
>> DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC (32, 20 in hexadecimal).

Because conforming implementations do not return it.


>> If other and reference are not in the same tree, return the result of adding DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, and either DOCUMENT_POSITION_PRECEDING or DOCUMENT_POSITION_FOLLOWING, with the constraint that this is to be consistent, together.
>
> I'm not sure what "together" means.

"Adding x and y together" is not a thing?


>> Whether to return DOCUMENT_POSITION_PRECEDING or DOCUMENT_POSITION_FOLLOWING is typically implemented via pointer comparison. In JavaScript implementations Math.random() can be used.
>
> I don't understand this either, especially not in the context of `together`

Does the above help?


> stray `,` after `If`

Fixed.


> there's a small gap here, but perhaps it would make sense to have a
> heading or section or something.

Not quite sure what that would say.


> https://dom.spec.whatwg.org/#dom-document-createeventinterface
>
>> "touchevent"     TouchEvent
>
> why are there red bars to the right of this?

There's no maintained document to point to.


>> Event constructors can be used instead.
>
> can => should ?
> rfc should meaning "unless you have a good reason not to, you should
> do so", needing to support some browser that doesn't support
> constructors is "a good reason" in rfc concept, otherwise, we'd rather
> people use the constructors, right?

We can't use should in non-normative context. Changed to "ought to"


>> Note: The Range() constructor can be used instead.

Also changed.


>> Set root and initialize the referenceNode attribute to the root argument.
>
> and => to the root argument and

Fixed.


>> Set whatToShow to the whatToShow argument.
>> Set filter to filter.
>
> Here (1/3) you don't use the construct `the {} argument`. This
> generally seems exceptional (based on a quick scan of the document).

Removed that construct.


> https://dom.spec.whatwg.org/#dom-document-createtreewalkerroot-whattoshow-filter

Also fixed.


> Bad link: http://www.w3.org/TR/xml/#NT-name
> Corrected: http://www.w3.org/TR/xml/#NT-Name
> Bad link: http://www.w3.org/TR/xml-names/#NT-qname
> Corrected: http://www.w3.org/TR/xml-names/#NT-QName

Well spotted! Fixed.


> either drop `a` or add `a` after `and`

Added an 'a'.


>> 5. Create a head element in the HTML namespace, and append it to the html element created in the previous step.
>> 6. If the title argument is not omitted:
>>    1. Create a title element in the HTML namespace, and append it to the head element created in the previous step.
>
> I'd half argue that "6." is the previous step, although I probably
> shouldn't :) -- you could say "in these steps" instead (there's only
> one, and it thus should work).
>
>> 7. Create a body element in the HTML namespace, and append it to the html element created in the earlier step.
>
> Or you could consistently use `earlier`

Done.


>> Applicable specifications and this specification (can) use the hooks…
>
> This specification uses and applicable specifications can use the hooks…

Mkay.


>> an attribute is set
>> an attribute is changed
>> an attribute is added
>> and an attribute is removed
>
> Either you should omit `an` from these or you should move it into the hook name.

I don't think that matters. Perhaps once we have a more consistent
naming schemes for these things...


> https://dom.spec.whatwg.org/#concept-element-attributes-get-by-namespace
>
>> Return the attribute in element’s attribute list whose namespace is namespace and local name is localName, if any, and null otherwise.
>
> Does this mean that there can be only one? --
> https://dom.spec.whatwg.org/#concept-element-attributes-get-by-name
> doesn't have this constraint.

Yup.


> You switch from the plural to the singular between these two
> sentences. You could do `Each element`. Does the first sentence mean
> that there might not be an associated DOMTokenList object?

Clarified.


> pattern:
> Either when => When

Fixed.


>> A node’s parent of type Element is known as a parent element. If the node has a parent of a different type, its parent element is null.
>
> I'm pretty sure my parsing of this doesn't match what you want to say.
>
> Can you give an example?

If a text node is the child of an element its parent element would be
that element. If its the child of a DocumentFragment its parent
element would be null.


> This doesn't mention returning undefined
>
>> The removeAttribute(name) method must remove an attribute given name and the context object, and then return undefined.
>> The removeAttributeNS(namespace, localName) method must remove an attribute given namespace, localName, and the context object, and then return undefined.
>
> Why do these?

"remove an attribute" returns something.


> you sometimes don't <sup> your th's

Fixed.


>> s
>> comment = new Comment([data = ""])
>
> not sure what the `s` is doing…

Removed.


> please swap the order of these two :)

Sure.


>> There exists some partially contained node if and only if the start node and end node are different.
>
> some … node => … nodes
> or
> some … node => some … nodes

some -> a.


>> The commonAncestorContainer attribute value is never contained or partially contained.
>
> never … or => neither … nor

Done.

>> A wild Range() constructor appeared.
>
> appeared => was added

Meme!

Thanks!


-- 
https://annevankesteren.nl/

Received on Tuesday, 30 June 2015 08:43:12 UTC