Adding dev documentation for chrome.location

chrome/common/extensions/api/location.idl

 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 // TODO(vadimt): Consider reusing WebKit/Blink types, if this is possible.
 
-// The <code>chrome.location</code> API augments the events from the
-// <a href="http://dev.w3.org/geo/api/spec-source.html">HTML Geolocation API</a>
-// to be event page compatible.
+// Use the <code>chrome.location</code> API to retrieve geographical location of
+// the hosting machine.

[not at google - send to devlin, 2013/07/27 01:51:49]

i preferred the old description

[vadimt, 2013/07/27 02:08:55]

That was a pretty head-scratchy description for the user :)

The user probably wants to see something more digestible and actionable, like:

Use the chrome.alarms API to schedule code to run periodically or at a specified
time in the future.

Also, it creates a false impression that the API is literally a wrapper around
that API, which is not true, despite the fact that they share 99% of
implementation.

[Jeffrey Yasskin, 2013/07/27 03:00:29]

Can we combine them? I agree that your new description is much better for new
users, but I think experienced HTML5 folks will wonder how it's different from
the geolocation API they already know, and why we invented our own. What if you
add a sentence "This is a version of the <a
href="http://dev.w3.org/geo/api/spec-source.html">HTML Geolocation API</a> that
is compatible with event pages." ?

[not at google - send to devlin, 2013/07/29 14:45:12]

Yes exactly. This was going to be my next comment. You need to make this clear
somewhere.

I like it in the description; I definitely want to see it in the intro section.

[vadimt, 2013/07/30 01:58:41]

Done. Probably, a similar comment should be done for chrome.alarms API?

 namespace location {
   // Coordinates part of the Location object.
   dictionary Coordinates {
     // The geographic latitude specified in degrees.
     double latitude;
 
     // The geographic longitude specified in degrees.
     double longitude;
 
     // The height of the position, specified in meters above the [WGS84]
@@ skipping 70 matching lines @@
   interface Events {
     // Fired when a location change is detected.
     // |location| : An object containing matching events and new location.
     static void onLocationUpdate(Location location);
 
     // Fired when detecting location in not possible.
     // |error| : Human-readable error description.
     static void onLocationError(DOMString error);
   };
 };