[geo2-ed] Review Comments

Section 5.2
-----------
* I suggest providing a PositionOptionsDict object so users can
feature-detect what properties the UA recognizes.  I'm pretty sure
another spec that uses an options object already does this, but I
can't find it at the moment.
* The first sentence after the IDL calls out three of the
PositionOptions values as being optional, but all five are optional.
* The default value sentences are all fairly clumsy.  I suggest "If
the XXX property is omitted from the PositionOptions object, or the
PositionOptions parameter is omitted entirely from a call to
getCurrentPosition or watchPosition, the default value is XXX."
* A better method in general for the previous suggestion would be to
define five spec variables for the call, specify up-front what their
default values are, then set their values differently with a sentence
like "If the PositionOptions parameter is provided to
getCurrentPosition or watchPosition, and the XXX property is present,
set the internal YYY variable to the property's value.".  This lets
you eliminate most of the "pre-processing" steps from section 5.1.
* "This may result in slower response times" - use "can" or "might"
here, as this isn't supposed to be a conformance criteria.
* The paragraph describing the timeout attribute explicitly says it
starts counting time from the call to the function, but then
contradicts itself by saying it actually starts counting time from the
permissions grant.  This should be rephrased to talk about the
permission grant immediately.
* The paragraph describing the maximumAge attribute doesn't actually
describe how to handle values other than 0 and Infinity.  It should do
so.
* The paragraph describing the requestAddress attribute doesn't have
any conformance criteria about what it should return, and the one
conformance sentence that does exist starts with the word "Note".  I
suggest "The requestAddress attribute indicates that the user agent
must attempt to provide a civic address in the returned Position.  All
fields of an Address are optional, and so an implementation that
cannot return position information must not treat this as causing the
overall location acquisition process to fail.  The intended purpose of
this attribute is to provide a means for user agents to avoid the
potentially expensive process of obtaining a civic address when it is
not required by the application."

~TJ

Received on Friday, 11 November 2011 16:30:58 UTC