[whatwg] Definitions of DOMTokenList algorithms andelement.classList

[Kristof Zelechovski]

I would consider it a big advantage to the posterity if the descriptions and
the algorithms were better formulated and ready to be understood in plain
text.  For example, regarding 2.8.3 DOMTokenList, (see appendix).  

LEGEND
Code samples are in braces; my comments are in brackets, and so are
important [*changes*], [-deletions-] and [+insertions+]. I understand this
effect cannot be automatically provided by the HTML view.

SUMMARY
Generic changes:
Find "index"; Replace "position";
Find "token argument"; Replace "given token"; 
[this is not strictly necessary, any uniformity would do]
Insert "the" where appropriate.
Specific changes: see below.

Cheers,
Chris

Appendix:

* { tokenCount = tokenList . length }
--- Returns the number of tokens in the string.

{ [*token*] = tokenList . item([*position*]) }
{ [+token =+] tokenList[[*position*]] }
--- Returns the token [*at the position given*]. The tokens are sorted
alphabetically.
[I would not say that a token has an index; an index is not a property of
the token.]

Returns null if [*the position*] is out of range.

{ hasToken = tokenList . has(token) }
Returns true if the token is present; false otherwise.
[
It may be slightly misleading to speak of tokens _in parameters_.  The
present description means that the corresponding LISP binding would be
{ (let ((has-token (ask token-list 'has 'token)))) }
Rather than
{ (let ((has-token (ask token-list 'has "token")))) }
Of course, I may be entirely wrong here in that the first snippet is what is
intended.
]

Throws an { INVALID_CHARACTER_ERR } exception if [+the+] token contains any
spaces.  
[In which case it is not a token at all, so this remark makes no sense.]

{ tokenlist . add(token) }
[*Inserts*] [+the+] token [+into the list+], unless it is already present.
[Inserts because the list implementation is sorted.]

Throws an { INVALID_CHARACTER_ERR } exception if [+the+] token contains any
spaces. [?]

{ tokenList . remove(token) }
Removes [+the+] token if it is present.

Throws an { INVALID_CHARACTER_ERR } exception if [+the+] token contains any
spaces. [?]

{ hasToken = tokenList . toggle(token) }
Adds [+the+] token if it is not present, or removes it if it is.
[Returns what?]

Throws an { INVALID_CHARACTER_ERR } exception if token contains any spaces.
[?]

The { length } attribute must return the number of unique tokens that result
from splitting the underlying string on spaces. This is the length.  [Why
this Biblical tone?]

The [*positions of the supported enumerated tokens within the list*] are the
numbers in the range [+from+] zero to length[*−*]1, unless the length
is zero, in which case there are no supported [*enumerated*] properties.

The { item([*position*]) } method must split the underlying string on
spaces, sort the resulting list of tokens by Unicode code point, remove
exact duplicates, and then return the [-indexth-] item in this list [+at the
given position+]. If [*the position*] is equal to the number of tokens or
greater, then the method must return null.

The { has(token) } method must run the following algorithm:

 1. If the [+given+] token [-argument-] contains any space characters, then
raise an { INVALID_CHARACTER_ERR } exception and stop the algorithm. 
 2. Otherwise, split the underlying string on spaces to get the list of
tokens in the object's underlying string. 
 3. If the [+given+] token [-indicated by token-] is one of the tokens in
the object's underlying string then return true and stop this algorithm. 
 4. Otherwise, return false. 

The { add(token) } method must run the following algorithm:

 1. If the [+given+] token [-argument-] contains any space characters, then
raise an { INVALID_CHARACTER_ERR } exception and stop the algorithm. 
 2. Otherwise, split the underlying string on spaces to get the list of
tokens in the object's underlying string. 
 3. If the given token is already one of the tokens in the { DOMTokenList }
object's underlying string then stop the algorithm. 
 4. Otherwise, if the { DOMTokenList } object's underlying string is not the
empty string and the last character of that string is not a space character,
then append a U+0020 SPACE character to the end of that string. 
 5. Append the [*characters*] of [+the+] token to the end of the {
DOMTokenList } object's underlying string. 

The { remove(token) } method must run the following algorithm:

 1. If the [+given+] token [-argument-] contains any space characters, then
raise an { INVALID_CHARACTER_ERR } exception and stop the algorithm. 
 2. Otherwise, remove the given token from the underlying string. 
[ 
You leave two consecutive spaces here.  
Why do you insist on not allowing an initial space above? ]

The { toggle(token)}  method must run the following algorithm:

[This algorithm is redundant because it is a secondary method that can be
implemented in terms of {has}, {add} and {remove}. ]

Objects implementing the DOMTokenList interface must stringify to the
object's underlying string representation.