comments on sensor API draft (1)

We’ve collected some suggestion on where the sensor API draft could be clearer – I’ll follow this up with a second email with some more.  This is from a couple different sources.

#1
Section 1 Introduction first example “session.startWatch(watchOptions);”



“session” is the wrong variable name.  It should be “sensorCnx”, not “sensor”



#2

Throughout the entire draft there is discussion of “done flag” as a Boolean “was set to false”.  Where is this “done” flag?  It seems done is only a value of “readyState” but that is defined in terms of the “done flag”.
readyState of type DOMString, readonly
Represents the status of the request. It must be set to one of the following:
·        processing. If the done flag is false.
·        done. If the done flag is true.

#3

“must return the sensor's resolution of the sensor in the sensor's unit”

Phrases with “sensor in the sensor’s unit” are repeated.  It should say “unit of measurement” to make it easier for readers to parse the phrase



#4

“getting this property must return the error of the request”  -- “getting this property” occurs in multiple places.  It’s awkward to read in sentences that have a verb immediately following it.  better to drop “getting this property” and just say something like “must return the error”



#5

In section 5.1.1 Attributes  --  the attribute descriptions are listed below in alphabetical order, rather than the order in which they appear.  That seems unnatural.  Throughout the draft, parameter descriptions are in alphabetical order rather than the order in which they appear in the object.



#6

Section 5.1.1
type of type DOMString, readonly
It must return the sensor type. See table below for a list sensor types defined by this specification

There should be a link to the table it is referring to.   This would mean to imply that the only valid types are in that table.  It would be better to explicitly state other sensor types could be added outside of this specification.



#7

Section 6.2 Sensorwatchoptions threashold

Only checking for going below a particular value isn’t good.  Better to have it be an array with low threshold, high threshhold?  Perhaps make it a high and low threshold?  Or an array to have low, high and whatever else specific sensor types want.



#8

MUST should be capitalized “hardware and must be expressed”



#9

Section 6.4 “Once the spec progress this section will be changed to comply with the DOM4 Event interfaces”   - drop the words “once the spec progress”



#10

Section 6.4.1 Sensordataevent  “reason” is a name that doesn’t seem to reflect what it is.  This is information on whether this is onetime or a watch recurreing report.  Or the attribute could be a Boolean “watchpoint” where true only if a recurring watch.



#11

Section 7 isn’t really “requirements”. It looks more like describing formats for particular types of sensors.  It should say here how others create their own additions.  Is there a registry?  Do people use prefix’s for their own namespace?