Re: api comments

Thanks Allan.  I understand how using text might be harder.  However,  
now it is searchable in just about every email client and search  
engine, and comment-able by everyone that doesn't have a copy of Word.

some comments inline:


On Mar 30, 2009, at 10:32 AM, Allan Thomson (althomso) wrote:

> All – it would seem this is an extremely inefficient way to solicit  
> comments on the document. If you are open to alternate ways of  
> getting comments I have experience on how the IEEE does it which  
> makes it easier to track comments and respond to them. But here goes  
> anyway…
>
> Allan
>
>
> Introduction Section
>
>
> Comment #1:
>
> “The API is designed to enable both "one-shot" position requests and  
> repeated position updates”,
>
> This suggests a periodic update rather than what I think it is  
> intended to suggest is asynchronous updates. It is not clear from  
> the document when and what causes an asynchronous location update to  
> occur. It is movement? Time? Suggest that you change “repeated  
> position updates” to “asynchronous updates” and clarify what  
> triggers the updates to be sent.


I agree; this change makes it a bit more readable.  However, it should  
be clear that the update (asynchronous or "repeated position") is  
solely an implementation detail on when they are generated, how often  
they are provided back to the running application, etc.  For example,  
on a GPS device, we need to throttle the updates coming from the gps  
so that we can maintain performance -- the GPS updates so frequently  
that the browser has a hard time keeping up.


> Comment #2:
>
> “…the ability to explicitly query the cached positions”
>
> Define cached? Where is it cached? Client or server side? What is  
> the criteria for caching vs not caching.  Suggest the concept of  
> caching is not something this API should address or should be a  
> separate document


We wanted some way to get back the "last known position" -- the  
position that the UA last saw.  Does cached really need to be defined  
in this context?



> Comment #6:
>
> This API provides a mechanism to provide location of the calling  
> agent ONLY. Might be obvious but I think it is worth stating due to  
> security concerns that may arise if someone thought they can use  
> this API to find out location of someone else.


I do not follow this argument.  There are lots of things that this API  
doesn't do that we are not enumerating.  What are you proposing we  
state here?

>
> API Description – Geolocation Interface
>
> Comment #7:
>
> interface Geolocation {
>     void getCurrentPosition(in PositionCallback successCallback);
>     void getCurrentPosition(in PositionCallback successCallback, in  
> PositionErrorCallback errorCallback);
>     void getCurrentPosition(in PositionCallback successCallback, in  
> PositionErrorCallback errorCallback, in PositionOptions options);
>
>     int watchPosition(in PositionCallback successCallback);
>     int watchPosition(in PositionCallback successCallback, in  
> PositionErrorCallback errorCallback);
>     int watchPosition(in PositionCallback successCallback, in  
> PositionErrorCallback errorCallback, in PositionOptions options);
>
>
> Are these methods completely orthogonal (i.e. thread safe)?
>
> i.e. can a client call multiple methods at the same time before a  
> result is received? What are the semantics of multi-threading  
> applications on this API. Suggest they should be thread safe and a  
> client can call methods multiple times without waiting for a  
> result.  If that is the case then each call of the method should  
> return a unique handle as part of the registration if the client is  
> to be able to differentiate results to each call of a method  
> especially if they are using the same callback method.


This is an implementation detail.


> Comment #8:
>
>   interface PositionCallback {
>     void handleEvent(in Position position);
>   };
>
>   interface PositionErrorCallback {
>     void handleEvent(in PositionError error);
>   };
>
>
> Why are there two functions rather than just one function with a  
> status code? For example there may be situations where a location  
> object will be returned but some additional status still needs to be  
> conveyed back to the caller also. In that case there is no way to do  
> that right now. Also, having two methods will create code bloat  
> unnecessarily.
>
> Suggest make a single method for callback with a status object (code  
> + other attributes) and a location position object.
>

It models the XHR.  This was discussed previously on the mailing list.


> Comment #9:
>
> “The getCurrentPosition() takes one, two or three arguments. When  
> called, it must immediately return and then asynchronously acquire a  
> new Position object. If successful, this method must invoke its  
> associated successCallback argument with a Position object as an  
> argument. If the attempt fails, and the method was invoked with a  
> non-null errorCallback argument, this method must invoke the  
> errorCallback with a PositionError object as an argument”
>
> The getCurrentPosition method needs to return a success or failed  
> result code so that the caller knows the callback has been  
> registered successfully. Or define an exception but there needs to  
> be a way for an implementation to return “callback not registered”  
> or other unusual programmatic errors.


Implementations may throw if there is a programatic error that we can  
detect when the method is invoked.  We probably should spell that out.

>
> API Description – PositionOptions Interface
>
> Comment #10:
>
> “The enableHighAccuracy attribute provides a hint that the  
> application would like to receive the best possible results. This  
> may result in slower response times or increased power consumption.  
> The user might also deny this capability, or the device might not be  
> able to provide more accurate results than if the flag wasn't  
> specified”
>
> The definition of “high” accuracy is dependent on many things  
> outside the control of the user and they have no way of  
> understanding why they are or are not getting high accuracy.  99%  
> clients will always want the best accuracy you can give. Suggest you  
> remove this attribute as it is not useful and will cause many  
> comments in the future on what is the definition of high accuracy.

There was lots of discussion on this field previously.  I was in favor  
of removing it, but others liked it.  I am not sure if we should  
reopen this issue.  Andrei?

> Another possible option is to define a polygon and error estimates  
> on the location result so that you can represent accuracy more  
> correctly. To do this see comment regarding X,Y positional  
> information in civic attributes.

no polygons in this API. please.

>
> API Description – Coordinates Interface
>
> Comment #11:
>
>   interface Coordinates {
>     readonly attribute double latitude;
>     readonly attribute double longitude;
>     readonly attribute double altitude;
>     readonly attribute double accuracy;
>     readonly attribute double altitudeAccuracy;
>     readonly attribute double heading;
>     readonly attribute double speed;
>   };
>
> Heading/Direction (less so) and speed (more so) are not specific to  
> geospatial information AND are common to both civic as well as  
> geospatial location objects. Suggest heading/direction and speed  
> should be a separate object that can be referenced by both civic and  
> geospatial positions.


+1



> API Description – Address Interface
>
> Comment #12:
>
>   interface Address {
>     readonly attribute DOMString country;
>     readonly attribute DOMString region;
>     readonly attribute DOMString county;
>     readonly attribute DOMString city;
>     readonly attribute DOMString street;
>     readonly attribute DOMString streetNumber;
>     readonly attribute DOMString premises;
>     readonly attribute DOMString additionalInformation;
>     readonly attribute DOMString postalCode;
>   };
>
> This object is missing attributes for
>
> 1)       Building
> 2)       Floor
> 3)       Area
> 4)       X,Y (on a floor) or a polygon that represents the position  
> and error at the same time
>
> Comment #13:
>
> AdditionalInformation is inadequate for the “rest” of the  
> information for buildings, floors…etc as the spec currently states.


Why is it inadequate?  Isn't there a conversion possible?


> API Description – PositionError Interface
>
> Comment #14:
>
> Need to add “format unavailable” for times when lat/long or civic  
> formats are not available due to lack of support of a particular  
> format either from the underlying location determination capability  
> or environment you are currently in. This is different from a  
> position being unavailable due to lack of gps sync or civic  
> information available from a location server due to network problems.


+1  We need this when the PositionOptions allows one to specify which  
Position type they want.


>
> Comment #16:
>

Received on Monday, 30 March 2009 17:59:45 UTC