Screen orientation API feedback

"Unless stated otherwise, the term screen is ..." Does it ever state
otherwise? Please remove the conditional if not.


"a Promise object whose associated task" Instead of "task" use a word
like "operation" so readers are not confused with the event loop from
HTML.


"Unless specified otherwise, when queuing a task, ..." You never state
otherwise. I would ask you to remove the conditional, but I think
screen orientation changes ought to be relayed during the "animation
frame task". See
http://lists.w3.org/Archives/Public/www-dom/2014JulSep/0061.html for
context.


"the values of type and angle will be strongly linked" It might be
better to talk about the abstract underlying concepts here as type and
angle have no values. They have getters. Also, shouldn't these values
be updated based on the animation frame task rather then return
something when reading them? It seems doing the operation on reading
creates racing issues, e.g. no guarantee that obj.angle === obj.angle,
and might cause some amount of locking.


Rather than using DOMException, can we simply use JavaScript's
TypeError? What we want with DOMException hasn't been figured out and
using TypeError works just as well. Or are there scenarios here where
you want branching based on the exception? That would be interesting
to know.


"apply an orientation lock" has no information about context. E.g.
what document are we talking about here? That could be more explicit.
That it has to be a top-level browsing context's document is also
unclear.


"Set pending promise to be null." To be or not to be? "to null" would be better.


"If the active orientation lock is not the current orientation lock"
how does this work given that at least current orientation lock is a
list? (It would help to rename these variables to more clearly
indicate what is a list. That might also help avoid such errors.


The way the task queuing happened is also bad by the way. You are
queuing a task to perform an asynchronous operation (locking). You
first want to change the orientation and only then queue a task (well,
do something with the animation frame task) to synchronize state.


"fullscreen enabled flag has been set (i.e., when the document is in
fullscreen)" I think you misunderstand the fullscreen enabled flag. It
does not mean this.


"Fire a simple event named change at each screen.orientation object."
This needs to talk about the actual objects or you need to ensure you
talk about resolving this reference before any developer code got a
handle on the screen reference, let alone the orientation reference.
Typically you would enumerate the objects somehow.


(Sorry for not having all of it in order and for it being incomplete.
Will review again once the major pieces have been reshuffled to be
correct.)


-- 
http://annevankesteren.nl/

Received on Tuesday, 5 August 2014 10:30:57 UTC