[wake-lock] Duplicate (?) normative requirements (#143)

domenic has just created a new issue for https://github.com/w3c/wake-lock:

== Duplicate (?) normative requirements ==
https://w3c.github.io/wake-lock/#wake-locks has a bunch of "MUST"s and "MAY"s that are pretty vague.

Some of them (all of them?) seem to duplicated (or maybe contradicted? can't really tell) by the algorithms in the method definitions. For example, 

> If Document's feature policy disables the wake lock feature, the user agent MUST deny wake lock.

Seems to be duplicated by

> 1. If this Document is not allowed to use the policy-controlled feature named wake-lock, return a promise rejected with a newly created SecurityError.

But I guess it's also contradicting the later steps:

> 8. Determine whether the user agent will deny wake lock of this type for this Document.
>
> 9. If the user agent has determined that it will deny the wake lock, set wakeLockResolution to rejected wake lock resolution, reject wakeLockPromise with a new "NotSupportedError" DOMException and abort these steps.

I.e., it's not clear from the spec as written whether it should be a SecurityError, or a "NotSupportedError" DOMException, when the feature policy disallows wake locks.

---

I would suggest removing all normative requirements from the introductory material, and keeping them in the algorithms. You could have an informative, loose summary in the intro, but it should not include MUST or MAY, and it needs to refer explicitly to the algorithms to explain that's where the normative requirements are defined.

Please view or discuss this issue at https://github.com/w3c/wake-lock/issues/143 using your GitHub account

Received on Thursday, 20 December 2018 19:56:15 UTC