RE: Review of Sensor API Specification 09 April 2012

Comments below

>-----Original Message-----
>From: Marcos Caceres [mailto:marcosscaceres@gmail.com]
>Sent: Wednesday, April 11, 2012 5:16 AM
>To: public-device-apis@w3.org
>Subject: Review of Sensor API Specification 09 April 2012
>
>Review of Sensor API Specification  09 April 2012
>
>On Wednesday, April 11, 2012 at 12:56 PM, Marcos Caceres wrote:
>
>> This specification defines an API for getting access to information provided by
>sensors available from a hosting device.
>
>I don't think you should say hosting device. It should be generalized (so to support
>remove sensors, etc.).

[[Wayne Carr]] 
This is not the generalized API.  This is the specific, direct API for sensors on the device.  In the future, another more general API can be produced using WebIntents that can locate local sensors and services.  This is for the direct API that some in this WG prefer to the more general Web Intents approach.  There is no reason not to have an API for what is on the device and a more general API for finding what services are available in the local network.

>
>>
>> 1. Introduction
>>
>> This section is non-normative
>>
>> This specification defines an API that allows application code to obtain
>information given by the various sensors available on a hosting device. The
>information provided through this API is raw sensor data. The specification is
>aimed at covering well-known sensors that are commonly found in devices.
>
>
>Has consensus been reached to limit this to "sensors commonly found in
>devices"? My use case is to plug this API to use with an Arduino (to which I can
>plug all sorts of sensors to). If it has, what are the devices?
>

[[Wayne Carr]] 
Same as above.  This isn't meant for local network discovery.  That would be a different spec.

>> 3. Security and Privacy Considerations
>>
>> A conforming implementation of this specification must provide a mechanism
>that protects the user's privacy and this mechanism should ensure that no
>sensitive information is made available through this API without the user's
>express permission.
>
>The above is not helpful. Bake it into the API and remove the above.
>

[[Wayne Carr]] 

Isn't this a common approach in other specs?

>> User agents must acquire permission through a user interface, unless they have
>prearranged trust relationships with users.
>
>
>
>As above. Please remove this and bake it into the API at the appropriate point.
>
>>
>> 4. Sensor Manager
>Move this to 4.1 (or move 4.1 up here!)
>>
>> Navigator implements SensorManager;
>
>
>Because of the above, the following sentence is redundant (WebIDL already says
>this… remove it please):
>> All instances of the Navigator type are defined to also implement the
>SensorManager interface.

[[Wayne Carr]] 
Isn't it OK to have clarifying sentences for readers who are more comfortable with that description.  It seems a matter of style, not an error.

>
>
>
>Also, you don't say how to implement on navigator. You need to say:
>
>[NoInterfaceObject]
>interface NavigatorSensorManager {
>readonly attribute SensorManager SensorManager; }; Navigator implements
>SensorManager;
>
>
>>
>> 4.1 SensorManager
>>
>> This is an asynchronous API that returns without blocking the calling thread.
>The above is redundant if it's already stated in the algorithms. Please remove it.

[[Wayne Carr]] 
Same as above.  Isn't it OK to make it clear to readers who may not read the algorithm.  This too seems a matter of style.  Some readers would prefer it in an English sentence for clarity.

>> This interface provides interfaces to applications for making sensor requests.
>
>
>Sensor request is not defined. I think the above sentence is redundant:
>functionality is defined by the exposed methods, not by the interface itself (which
>is a way to get at functionality).
>> [NoInterfaceObject]
>
>
>Why is this a NoInterfaceObject?
>> interface SensorManager {
>> void cancelWatchpoint (SensorRequest request); void connectSensor
>> (SensorRequest request, SensorSuccessCallback onSuccess, optional
>> callback onFailure); };
>
>
>I think Sensors should manage themselves….
>
>Looking further at the spec, I see that almost all the issues I raised in my previous
>email are still present in this version. I would appreciate if you could go over my
>previous feedback and just delete things that don't apply any more (it saves me
>doing the same review again):
>
>http://lists.w3.org/Archives/Public/public-device-apis/2012Mar/0094.html

>
>Kind regards,
>Marcos
>

Received on Wednesday, 11 April 2012 16:01:45 UTC