Review of DOM Living Standard — Last Updated 20 June 2015

https://dom.spec.whatwg.org/#dom-node-comparedocumentpositionother

[green box]
> node . compareDocumentPosition(other)
>     Returns a bitmask indicating the position of other relative to node. > These are the bits that can be set:
> Node . DOCUMENT_POSITION_DISCONNECTED (1)
>     Set when node and other are not in the same tree.
> Node . DOCUMENT_POSITION_PRECEDING (2)
>     Set when other is preceding node.
> Node . DOCUMENT_POSITION_FOLLOWING (4)
>     Set when other is following node.
> Node . DOCUMENT_POSITION_CONTAINS (8)
>     Set when other is an ancestor of node.
> Node . DOCUMENT_POSITION_CONTAINED_BY (16, 10 in hexadecimal)
>     Set when other is a descendant of node.

…
> These are the constants compareDocumentPosition() returns as mask:
…
> DOCUMENT_POSITION_CONTAINED_BY (16, 10 in hexadecimal);

this is missing from the green box:
> DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC (32, 20 in hexadecimal).

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

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

https://dom.spec.whatwg.org/#dom-node-lookupprefixnamespace

> If element's namespace is namespace and its namespace prefix is not null, return its namespace prefix.
> If, element has an attribute whose namespace prefix is "xmlns" and value is namespace, then return element's first such attribute's local name.

stray `,` after `If`

> The removeChild(child) method must return the result of pre-removing child from the context object.

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

> The list of elements with local name localName for a node root is the HTMLCollection returned by the following algorithm:

https://dom.spec.whatwg.org/#dom-document-createeventinterface

> "touchevent"     TouchEvent

why are there red bars to the right of this?

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

https://dom.spec.whatwg.org/#dom-document-createrange

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

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

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

and => to the root argument and

I know what you're trying to say, but I don't think the parallelism works.

It could be read as "Set root [to empty/default] and …"

w/ my change, you could do:
to the root argument. => to it.

if you want to avoid saying `the root argument` twice…

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

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

See previous comments.

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

> doctype = document . implementation . createDocumentType(qualifiedName, publicId, systemId)

> If qualifiedName does not match the Name production, an InvalidCharacterError exception is thrown,

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

> and if it does not match the QName production, a NamespaceError exception is thrown.

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

https://dom.spec.whatwg.org/#dom-domimplementation-createdocumenttypequalifiedname-publicid-systemid

> Note: No check is performed that publicId matches the PublicChar production or that systemId does not contain both a '"' and "'".

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

https://dom.spec.whatwg.org/#dom-domimplementation-createhtmldocumenttitle

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

https://dom.spec.whatwg.org/#interface-element

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

This specification uses and applicable specifications can use the hooks…

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

Offhand, I favor the latter.

https://dom.spec.whatwg.org/#concept-element-attributes-get-by-name

> Return the first attribute in element’s attribute list whose name is name, and null otherwise.

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.

> Elements can have an associated unique identifier (ID)
and have an associated DOMTokenList object.
> The DOMTokenList object’s associated attribute’s local name is class and its associated ordered set of tokens is called the element’s classes.

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?

> Either when an element is created that has an id attribute whose value is not the empty string or when an element’s id attribute is set to a value other than the empty string, set the element’s ID to the new value.

pattern:
Either when => When

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

https://dom.spec.whatwg.org/#dfnReturnLink-43
>  void setAttributeNS(DOMString? namespace, DOMString name, DOMString value);
>  void removeAttribute(DOMString name);
>  void removeAttributeNS(DOMString? namespace, DOMString localName);

https://dom.spec.whatwg.org/#dom-element-setattributensnamespace-name-value

> The setAttributeNS(namespace, name, value) method must run these steps:
>    Let namespace, prefix, localName, and name be the result of passing namespace and name to validate and extract. Rethrow any exceptions.
>    Set an attribute value for the context object using localName, value, and also name, prefix, and namespace.

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?

https://dom.spec.whatwg.org/#dom-domtokenlist-itemindex
> Return the indexth token in tokens.

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

https://dom.spec.whatwg.org/#concept-CD-substring

> If offset plus count is greater than length, return a string whose value is the code units from the offsetth code unit to the end of node’s data, and then terminate these steps.

here you did. it's certainly easier on my eyes to read <sup>'d th's
(although my spellchecker isn't smart enough to know to ignore them,
but that's a bug i could probably fix if the markup was present…)

https://dom.spec.whatwg.org/#interface-comment

> s
> comment = new Comment([data = ""])

not sure what the `s` is doing…

https://dom.spec.whatwg.org/#partially-contained

> The first contained node (if there are any) will always be after the start node, and the last contained node will always be equal to or before the end node’s last descendant.
> The start node and end node of a range are never contained within it.

please swap the order of these two :)

> 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

> The commonAncestorContainer attribute value is never contained or partially contained.

never … or => neither … nor
or
never … or => never … and never

https://dom.spec.whatwg.org/#dom-ranges-changes

> A wild Range() constructor appeared.

appeared => was added

??

Received on Monday, 22 June 2015 22:41:48 UTC