- From: timeless <timeless@gmail.com>
- Date: Mon, 1 Jun 2015 14:23:01 -0400
- To: "public-geolocation@w3.org" <public-geolocation@w3.org>
http://www.w3.org/TR/2015/PER-geolocation-API-20150528/
> The API itself is agnostic of the underlying location information sources.
> Common sources of location information include Global Positioning System (GPS)
> and location inferred from network signals such as IP address,
> RFID,
> WiFi and Bluetooth MAC addresses,
> and GSM/CDMA cell IDs,
> as well as user input.
There are a bunch of "and" tokens in this sentence, some of them
probably don't belong.
> Those permissions that are acquired through the user interface and that are preserved beyond the current browsing session
> (i.e. beyond the time when the browsing context [BROWSINGCONTEXT] is navigated to another URL)
> must be revocable and user agents must respect revoked permissions.
revoked permissions => permission revocation
> For example,
> while a Web browser will present a user interface when a Web site performs a geolocation request,
> a VOIP telephone may not present any user interface when using location information to perform an E911 function.
VOIP => VoIP
> In ECMAScript, the enableHighAccuracy , timeout and maximumAge properties are all optional: when creating a PositionOptions object, the developer may specify any of these properties.
> In case of a getCurrentPosition() call, the errorCallback would be invoked at most once. In case of a watchPosition() , the errorCallback could be invoked repeatedly: the first timeout is relative to the moment watchPosition() was called or the moment the user's permission was obtained, if that was necessary. Subsequent timeouts are relative to the moment when the implementation determines that the position of the hosting device has changed and a new Position object must be acquired.
The links in this document are often (but not always) of the form: {<a
href="...">this </a>}, the trailing space should be outside the
anchor. -- This comment applies to the entire document.
> The getCurrentPosition()* method takes one, two or three arguments.
http://www.w3.org/TR/2015/PER-geolocation-API-20150528/#get-current-position
> When called, it must immediately return and then asynchronously attempt to obtain the current location of the device.
> If the attempt is successful, the successCallback* must be invoked
>> void getCurrentPosition([PositionCallback successCallback],
>> optional PositionErrorCallback errorCallback,
> (i.e. the handleEvent* operation must be called on the callback object)
[I can't figure out where this is at ALL]
> with a new Position* object, reflecting the current location of the device.
http://www.w3.org/TR/2015/PER-geolocation-API-20150528/#position
> If the attempt fails, the errorCallback* must be invoked with a new PositionError* object,
>> void getCurrentPosition(PositionCallback successCallback,
>> optional [PositionErrorCallback errorCallback],
http://www.w3.org/TR/2015/PER-geolocation-API-20150528/#position-error
> reflecting the reason for the failure.
It would be helpful if each of these *'d items linked to their
definition (this also applies to the next two blocks at least).
> The implementation of the getCurrentPosition* method must execute the following set of steps:
http://www.w3.org/TR/2015/PER-geolocation-API-20150528/#get-current-position
> If a cached Position* object, whose age is no greater than the value of the maximumAge* variable,
http://www.w3.org/TR/2015/PER-geolocation-API-20150528/#position
http://www.w3.org/TR/2015/PER-geolocation-API-20150528/#max-age
> is available,
> invoke the successCallback* with the cached Position object as a parameter and exit this set of steps.
...
Note that "cached" is potentially underdefined.
consider the following:
var callcount = 0;
function getit() {
navigator.geolocation.getCurrentPosition(callback, undefined,
{maximumAge:Infinity, timeout:0});
}
function callback(pos) {
if (callcount++ && pos.cached) { alert("it was really cached") }
pos.cached = true;
}
setTimeout(getit, 0);
setTimeout(getit, 0);
should I expect to see the alert?
It's possible that you mean that just the values are available, and
not that implementations should actually recycle the object itself.
Testing with Firefox/38.0 shows that the object is not recycled,
although the underlying values are.
(Also, the permission model doesn't seem to work as I'd expect, but whatever.)
> The watch operation must continue until the clearWatch method is called with the corresponding identifier.
No mention is made about document lifespan, I'd half expect something
to tell me that the watch will terminate when the page is torn down or
something.
These two instructions:
> 2. Register to receive system events that indicate that the position of the device may have changed (e.g. by listening or polling for changes in WiFi or cellular signals).
> 3. Start a location acquisition operation (e.g. by invoking a platform-specific API),
... differ significantly in how they define / expect the UA to handle
things. The first mandates a system call, and the second is flexible
about UA implementation details. Given that 2 only has a "may" at the
end, the mandated "register to..." seems overly-prescriptive.
> 4.1. If the timer is not already running, start a timer that will fire after the number of milliseconds denoted by the value of the timeout variable. When the timer fires, invoke the errorCallback (if present) with a new PositionError object whose code attribute is set to TIMEOUT and jump to step 6.
There is no step 6. And I don't recall anything defining "step after last step".
Also, what happens for: watchPosition(..., {timeout:0})
> 4.2.2 If the new position differs significantly from the previous position, invoke the successCallback with a new Position object that reflects the result of the acquisition operation. This step may be subject to callback rate limitation (see below).
If the new position doesn't differ significantly from the previous
position, what do I do?
> 4.3 Else, if the location acquisition operation reports an error before the timeout expires, invoke the errorCallback (if present) with a new PositionError object whose code is set to POSITION_UNAVAILABLE. This step may be subject to callback rate limitation (see below).
This else is in reference to 4.2, so I don't think it's an else to 4.2.2.
I can reach:
> 5. Wait for a system event to be received. When such an event is received jump to the acquisition steps above.
But under this model, if I never receive an interesting system event,
the timer which was canceled at 4.2.1 will not be reinstantiated, and
the "loop" won't resume. That might be perfect, or perhaps my system
events aren't so great and my device can in fact get new location
information without events from 2.
> Furthermore, in steps 5.2.2 and 5.2.3, implementations may impose limitations on the frequency of callbacks so as to avoid inadvertently consuming a disproportionate amount of resources.
This section should have a heading. The fact that it's reachable via
"See below" without a heading is less than ideal.
> the watch process identified by the watchId argument must be immediately stopped and no further callbacks must be invoked.
no further callbacks must be invoked => further associated callbacks
must not be invoked
> when creating a PositionOptions object, the developer may specify any of these properties.
any => any or all
> Note that the time that is spent obtaining the user permission is not included in the period covered by the timeout attribute.
Note that excluding this time enables the application to measure the
time it takes for a user to reject a request, which is a privacy
violation. This should at least be disclosed to implementers as a
consideration if not actually addressed.
> Setting the maximumAge to Infinity must determine the implementation to return a cached position regardless of its age.
"determine" isn't the right word here, you're trying to say
"instructs", but the "must" is awkward.
> This version of the specification allows one attribute of type Coordinates and a timestamp.
"one attribute of ... and a timestamp" is poor form. It implies that
the timestamp isn't an attribute, which is clearly not what you mean.
> A group of friends is hiking through the Scottish highlands.
http://en.wikipedia.org/wiki/Scottish_Highlands
it's a proper noun, please capitalize Highlands.
> (e.g. images, video, audio)
missing "and" or ", ..."
> which allows the application to anticipate any changes of direction that the user might need to do.
do => take
Received on Monday, 1 June 2015 18:23:29 UTC