Re: Review of Sensor API Specification 09 April 2012

On Wednesday, April 11, 2012 at 5:01 PM, Carr, Wayne wrote:

> Comments below
>  
> [[Wayne Carr]]  
> This is not the generalized API. This is the specific, direct API for sensors on the device.

Ok, I know this is a dumb question, but "which device?" Maybe we can scope it a bit to a class of hardware (I know that this is kinda defined at the end of the spec, but would be good to scope the API at the start of the document).       
> 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.

I guess I was viewing this as a "black box": I was being agnostic to where the sensors are (they may have been rediscovered a priori through network discovery or interest)… I just want to interface with them consistently once I have them all (or as they become available automagically).  
> >  
> > >  
> > > 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.

Ok, if my conceptual model does not hold, then ignore my comment.  
> > > 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?
Perhaps, but that doesn't make it right :)   

> >  
> > 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.

The problem is that it can introduce errors because the prose can contradict the IDL.  Also, it may mean that they tester/implementer is forced to make a choice between prose and WebIDL. For the sake of clarity and reducing the risk of introducing errors, it's best to leave such things out (or clearly mark them as non-normative). It also doubles the maintenance work on the spec.  

> > 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.

I generally apply the rule of "Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away." Specs should not state things twice if possible.

If required to give the reader a nice overview of the architecture, then the introduction is a better place to gather such things. However, where there is normative text, the text should be as precise as possible (complimented by examples to provide further conceptual clarity).

Received on Wednesday, 11 April 2012 17:29:41 UTC