Re: [ambient light events LC] Feedback ( LC-2736)

 Dear Tab Atkins Jr. ,

The Device APIs Working Group has reviewed the comments you sent [1] on the
Last Call Working Draft [2] of the Ambient Light Events published on 13 Dec
2012. Thank you for having taken the time to review the document and to
send us comments!

The Working Group's response to your comment is included below, and has
been implemented in the new version of the document available at:
https://dvcs.w3.org/hg/dap/raw-file/tip/light/Overview.html.

Please review it carefully and let us know by email at
public-device-apis@w3.org if you agree with it or not before 28 Jan 2013.
In case of disagreement, you are requested to provide a specific solution
for or a path to a consensus with the Working Group. If such a consensus
cannot be achieved, you will be given the opportunity to raise a formal
objection which will then be reviewed by the Director during the transition
of this document to the next stage in the W3C Recommendation Track.

Thanks,

For the Device APIs Working Group,
Dominique Hazaël-Massieux
W3C Staff Contact

 1.
http://www.w3.org/mid/CAAWBYDAU-kYqB5DZqE3iVuxan2PPaBhhTj1hr1zPgn0R90yvQw@mail.gmail.com
 2. http://www.w3.org/TR/2012/WD-ambient-light-20121213/


=====

Your comment on the document as a whole:
> Heya!  I saw the LC announcement in public-webapps, and have some
> feedback.
> 
> * The introduction isn't very well written - it jumps straight into
> technical details (and too much of them), without adequate explanation
> of the purpose of the spec and the defined interfaces. I suggest
> replacing it with something like:
> 
> This specification defines events that provide information about the
> ambient light level, as measured by a device's light sensor.  A
> LightLevelEvent describes the light level as one of three simple
> categories - "dim", "normal", and "bright" - while a DeviceLightEvent
> provides a more granular answer by describing the light level in terms
> of lux units.
> 
> * Chapter 5 should start with an intro that describes the event.  It's
> fine for this to be somewhat repetitive with the spec's own intro -
> the point is to make it sensical for someone to jump straight into
> this section.  I suggest something like:
> 
> The DeviceLightEvent interface provides information about the ambient
> light levels, as detected by the device's light detector, in terms of
> lux units.
> 
> * Chapter 5 should have a note (for authors) that the precise lux
> value reported by different devices in the same light may be
> different, due to differences in detection method, sensor
> construction, etc.
> 
> * 5.1 and 5.2.3 seem to be duplicate information.  I suspect this is a
> result of ReSpec, but this should be avoided if possible.  Same for
> 6.1 and 6.2.3.
> 
> * Similar, Chapter 6 should have an intro.  I suggest something like:
> 
> The LightLevelEvent interface provides information about the ambient
> light levels, as detected by the device's light detector, in terms of
> three general range: "dim", "normal", or "bright".
> 
> * The LightLevelEvent interface should use a WebIDL enum, rather than
> describing the values solely in prose.  Here's the IDL necessary:
> 
> enum LightLevel { "dim", "normal", "bright" };
> [Constructor (DOMString type, optional LightLevelEventInit
> eventInitDict)]
> interface LightLevelEvent : Event {
>     readonly attribute LightLevel? value;
> };
> dictionary LightLevelEventInit : EventInit {
>     LightLevel? value;
> };
> 
> 
> * In 6.2.1 (the description of the allowed values for the
> LightLevelEvent.value attribute), "may" is used.  Either "must" should
> be used, or it should be made non-normative and switched to "can" or
> something.  I think the latter is appropriate, once the enum (above)
> is adopted, as the WebIDL constitutes sufficient normative
> requirements already.
> 
> * In 6.2.2 (the definition of how to fire the event), if the light
> level can't be determined, the .value attribute of the event should be
> null, not the empty string.  I've already handled the nullability in
> the WebIDL above.
> 
> * In 6.2.2, the prose is a little unclear about when to fire
> lightlevel events.  I recommend replacing the sentence starting with
> "When the current light changes..." and the following note with
> something like:
> 
> This specification does not define the exact lux ranges that the
> LightLevel values map to, as devices with different sensitivities may
> want to map them slightly differently.  However, it recommends that
> "dim" correspond to ambient light below 50lux, "normal" correspond to
> light between 50lux and 10000lux, and "bright" correspond to light
> above 10000lux.  User agents must fire a light level event when the
> current light level changes.  User agents may fire a light level event
> at any other time, for example if they have reason to believe that the
> page does not have sufficiently fresh data.
> 
> ~TJ


Working Group Resolution (LC-2736):
The WebIDL was changed to use enum as you suggested, thank you.

Changes were also made to address editorial comments, see the diff
https://dvcs.w3.org/hg/dap/rev/1c5fc74bd529



----

Received on Thursday, 17 January 2013 16:15:40 UTC