Re: Half a Review: Proximity Events - W3C Editor's Draft 16 May 2012

Hi Marcos,

On 17.5.2012, at 13.21, ext Marcos Caceres wrote:

> Hi,  
> Below is half a review of the 16 May Proximity Events spec… ran out of time to do the whole doc, sorry.   

This is an excellent start.

> On Wednesday, 16 May 2012 at 11:26, Marcos Caceres wrote:
> 
>> 1. Introduction
>> 
>> The DeviceProximityEvent interface provides web developers information about the distance between the hosting device and the nearby object.
> Please change to:   
> A DeviceProximityEvent informs a web developer that the proximity sensor of the hosting device has sensed a nearby object. Proximity sensors detect the presence of physical objects within a distance that is usually predefined by the sensor manufacturer.  

I changed the intro a bit. Feel free to embellish it.

[...]

>> The current device proximity is the distance between the hosting device and the nearby object, in centimeters.
> This is misleading. Distance is only the measure of the sensors's range. That is, a sensor can detect physical objects within 5cm… it can't tell you the distance because properties of materials screw with the sensor (see my other email about this).

What is your suggestion? I would not want to bring too much sensor hardware-specific quirks (e.g. re materials) to the spec.
  
>> The minimum device proximity is the minimum supported value for the current device proximity.
>> 
>> The maximum device proximity is the maximum supported value for the current device proximity.
> The above two are defined in "cm".   

They reference the current device proximity, so the unit of measurement is inherited.

>> The current user proximity state is a user-agent- and platform-specific approximation of the proximity of a physical object with the hosting device.
> Big warning needed here about how material properties change the ability for the proximity sensor to accurately detect distances.

I guess we may want to add a generic disclaimer somewhere stating that the accuracy of the proximity sensors may vary. Feel free to propose a text for that.

[...]

>> Create an event that uses the DeviceProximityEvent interface, with the name deviceproximity, which bubbles, is not cancelable, and has no default action, that also meets the following conditions:
>> If the implementation is unable to report the current proximity, initialize the value attribute to positive Infinity, otherwise initialize the attribute to the current proximity.
> 
> What's the rationale for using +Infinity?

I'd say +Infinity and -Infinity are more like placeholders at this point, up for debate.

We should define default values that are not likely to break *badly written* code such the following if the implementation is unable to report (some of) the values:

if (e.value === e.min) {
  // we're so close, or are we?

if (e.value < e.max) {
  // we're close, or are we?
}

if (e.value === e.max) {
  // this will always evaluate to true if the implementation
  // is unable to report the value and max values
}
   
>> If the implementation is unable to report the minimum device proximity, initialize the min attribute to negative Infinity, otherwise initialize the attribute to the minimum device proximity.
> 
> Why not just 0? Is there any sensor that can detect -cm?

The first example above might give a false positive, if the implementation is able to provide a valid value (0) for 'value', but is unable to report the min, and thus default to 0.

>> If the implementation is unable to report the maximum device proximity, initialize the max attribute to positive Infinity, otherwise initialize the attribute to the maximum device proximity.
> 
> Add: "in cm" to the end of the sentence.   

If we define the unit in the terminology section do we need to repeat it here?

> Now that I think about it, the above should be defined as part of the definition of min/max for the sensor (in the terminology section). It's not as if the min/max range of the sensor changes dynamically over time (or not for the common use cases, AFAIK). That keeps things related to the definition of min/max in one place. Then in the algorithm you can just say:  
> 
> "Initialize the min attribute to the minimum device proximity".
> 
> and:
> 
> "Initialize the max attribute to the maximum device proximity".

I tend to think the current prose makes it easier to grasp the algorithm.

> With links back to the the right definitions.  

Fixed.

Thanks for the review!

-Anssi

Received on Monday, 21 May 2012 09:37:24 UTC